# Troubleshoot DNS (https://developer.godaddy.com/en/docs/api-users/troubleshoot-dns) ## Overview This page covers errors you're likely to encounter when managing DNS records through the GoDaddy Domains API. For the full DNS management guide, go to [Manage DNS records](https://developer.godaddy.com/docs/api-users/manage-domains/dns). ## DNS changes not visible after update **Symptom:** You added or updated a DNS record and the change isn't reflected when you query the domain. **Cause:** DNS propagation is not instantaneous. There are two distinct timelines: * **Authoritative nameservers** (GoDaddy): changes apply within minutes. * **External resolvers** (Google 8.8.8.8, Cloudflare 1.1.1.1, ISPs): resolvers cache the old value for up to the previous TTL duration. **Resolution:** * Query the authoritative nameserver directly to confirm the change was applied: `dig @ns1.domaincontrol.com your-domain.com A` * If the authoritative server shows the new value, the change is live — you're waiting for resolver caches to expire. * If the authoritative server still shows the old value, verify the API call succeeded by reading the record: `GET /v3/domains/zones/{domain}/dns-records` * To reduce future propagation time, lower the TTL to 600 seconds before making a planned change, then restore it afterward. ## `400` when adding a DNS record **Symptom:** `POST /v3/domains/zones/{domain}/dns-records` returns `400` with a `fields` array. **Cause:** The request body failed field-level validation. Common causes: * **Invalid `type`**: Only supported record types are accepted (`A`, `AAAA`, `CNAME`, `MX`, `NS`, `TXT`, `SRV`, `CAA`). * **Malformed `data`**: An `A` record must have an IPv4 address, not a hostname. A `CNAME` must be a fully qualified domain name ending with `.`. * **`ttl` below minimum**: The minimum TTL is 600 seconds. * **Invalid `name` format**: Use `@` for the apex record, not the domain name itself. **Resolution:** * Inspect each item in the `fields` array — `path` identifies the field, `message` describes the constraint. * Verify the `data` format against the record type. For example: `"data": "192.0.2.1"` for an `A` record, `"data": "mail.example.com."` for an `MX` record. * Set `ttl` to at least `600`. ## `NS` or `SOA` records can't be modified **Symptom:** Attempting to delete or replace `NS` or `SOA` records returns an error or has no effect. **Cause:** GoDaddy manages `NS` and `SOA` records as part of its hosted DNS infrastructure. These records cannot be deleted or overwritten through the DNS records endpoint. **Resolution:** * To change nameservers, use the dedicated nameservers endpoint: `PUT /v3/domains/zones/{domain}/nameservers` with an array of new nameserver hostnames. * `SOA` records are system-managed and cannot be changed directly. Changes to `NS` records propagate the `SOA` automatically. * If you need to delegate DNS to an external provider (Route 53, Cloudflare), replace the nameservers entirely using the nameservers endpoint, then manage all records there. ## Duplicate record error on `POST` **Symptom:** `POST /v3/domains/zones/{domain}/dns-records` returns an error indicating a conflicting or duplicate record already exists. **Cause:** The `POST` endpoint appends records. If a record with the same type, name, and data already exists, or if adding the record would violate DNS constraints (for example, a `CNAME` at the apex, or conflicting `CNAME` and `A` records), the API rejects the request. **Resolution:** 1. Read the current zone: `GET /v3/domains/zones/{domain}/dns-records?type={TYPE}&name={NAME}` 2. Delete the conflicting record: `DELETE /v3/domains/zones/{domain}/dns-records/{recordId}` 3. Add the updated record: `POST /v3/domains/zones/{domain}/dns-records` To replace all records of a given type and name in one operation, use `PUT /v3/domains/zones/{domain}/dns-records/{type}/{name}`. ## `403 Forbidden` — insufficient scope **Symptom:** API returns `403` despite a valid token. **Cause:** The token doesn't include the scope required for the operation. **Resolution:** * Read operations require `domains.domain:read`. * Write operations (create, delete records) require `domains.dns:update`. * Nameserver replacement requires `domains.nameserver:update`. * Generate a new token with the correct scopes. Go to [Authenticate](https://developer.godaddy.com/docs/api-users/auth#pat-scopes) for the full scope list. ## `404 Not Found` — record or domain not found **Symptom:** API returns `404` on a read, delete, or nameserver operation. **Cause:** The `recordId` doesn't exist, the domain doesn't exist, or the domain isn't owned by the authenticated account. **Resolution:** * Verify the `zone` path parameter matches the domain name exactly (for example, `example.com`, not `www.example.com`). * For deletes: save the `recordId` from the `Location` header at create time. Don't construct `recordId` values manually. * Confirm the domain is visible via `GET /v1/domains` — if not found there, it isn't accessible with the current credential. ## `422 Unprocessable` — business rule violation **Symptom:** API returns `422` after accepting the request structure. **Cause:** The request is structurally valid but violates a DNS rule — the most common case is a `CNAME` at the zone apex. **Resolution:** * Do not create a `CNAME` record with `name: "@"` (the apex). Use `A`/`AAAA` records at the apex instead. * For `SRV` records, verify the `service` and `protocol` fields are underscore-prefixed (for example, `_http` and `_tcp`). ## `429 Too Many Requests` — rate limit exceeded **Symptom:** API returns `429`. **Cause:** The request rate exceeded the per-credential limit for the current window. **Resolution:** * Check the `Retry-After` response header and wait that many seconds before retrying. * For bulk operations, add a delay between requests or batch reads and writes. * Go to [Rate limits](https://developer.godaddy.com/docs/api-users/rate-limits) for the full rate limit reference.