# Troubleshoot DNS (https://developer.godaddy.com/en/docs/api-users/troubleshoot-dns)

***

title: Troubleshoot DNS
description: Common errors when managing DNS records with the GoDaddy Domains API, with causes and resolutions.
agentNotes:
scopes: \["domains.domain:read", "domains.dns:update", "domains.nameserver:update"]
idempotent: false
destructive: true
failureRecovery: "Read operations are safe to retry. DNS deletes are irreversible — re-read the zone after failures to verify state. If nameservers were replaced incorrectly, issue a corrective PUT immediately."
faqItems:

* question: "Why aren't my DNS changes showing up?"
  answer: "DNS propagation is not instantaneous. GoDaddy's authoritative nameservers apply changes within minutes, but external resolvers cache records for up to the previous TTL duration. Wait for the TTL to expire before assuming propagation has failed. Use a tool like dig @8.8.8.8 to bypass local cache."
* question: "Why do I get 400 when adding a DNS record?"
  answer: "The request body failed validation. Common causes: invalid record type, malformed data value (e.g. an A record with a hostname instead of an IP address), unsupported name format, or a TTL below the minimum (600 seconds). Check the fields array in the error response for the specific field and reason."
* question: "Why do I get 403 Forbidden on a DNS request?"
  answer: "The token doesn't include the required scope. Read operations need domains.domain:read, write operations need domains.dns:update, and nameserver replacement needs domains.nameserver:update. Generate a new token with the correct scopes."
* question: "Why do I get 404 on a DNS record operation?"
  answer: "Either the recordId doesn't exist, the domain doesn't exist in your account, or the domain name in the zone path parameter is wrong. Save the recordId from the Location header when you create a record — don't construct it manually. Verify the domain is visible via GET /v1/domains."
* question: "Why can't I delete NS or SOA records?"
  answer: "GoDaddy manages NS and SOA records as part of its hosted DNS infrastructure. These records cannot be deleted or overwritten through the DNS records API. To change nameservers, use the nameservers endpoint (PUT /v3/domains/zones//nameservers) instead."
* question: "Why does adding a CNAME return 422?"
  answer: "You can't add a CNAME at the zone apex (@ or the root domain). Use A/AAAA records at the apex instead. For SRV records, the service and protocol fields must be underscore-prefixed (e.g. \_http and \_tcp)."
* question: "Why am I getting 429 rate limit errors?"
  answer: "The API enforces a per-credential, windowed rate limit. 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 /docs/api-users/rate-limits for current values."
* question: "Why does my DNS record add keep returning a duplicate record error?"
  answer: "The POST /v3/domains/zones//dns-records endpoint appends records. If you already have a record with the same type, name, and data, the API may reject the duplicate depending on the record type. Read the current records first, then delete the existing one before adding the updated version."
* question: "How long does DNS propagation take after a record change?"
  answer: "GoDaddy's authoritative nameservers apply changes within minutes. External resolvers (Google, Cloudflare, ISPs) cache the old values for up to the previous TTL duration. If the old TTL was 3600 seconds (1 hour), expect up to 1 hour for global propagation. Lowering the TTL before a change speeds up subsequent propagation."
  related:
  guides:
  * title: "Manage DNS records"
    href: "/docs/api-users/manage-domains/dns"
  * title: "Troubleshoot your first API call"
    href: "/docs/api-users/troubleshoot-first-call"
  * title: "Troubleshoot authentication"
    href: "/docs/api-users/troubleshoot-authentication"
    apis:
  * title: "Domains v3 — DNS records"
    href: "/docs/references/rest/domains/v3/records"
    concepts:
  * title: "Error handling"
    href: "/docs/api-users/errors"

***

## 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.