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.

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 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 for the full rate limit reference.

Last updated on