Errors#

Every error says what went wrong in plain words. The texts are the same in all six styles; only the shape around them changes. This page shows each shape, lists the texts, and says what to do.

How errors look in each style#

Style	HTTP status	Where the text is
Dynadot	Always 200	`"ResponseCode": "-1"` and `Error`
Spaceship	4xx / 5xx	`{"detail": "...", "data": []}`
Cloudflare	4xx / 5xx	`"success": false`, `errors[0].message` (and `errors[0].code`)
GoDaddy	4xx / 5xx	`{"code": "...", "message": "..."}`
Porkbun	4xx / 5xx	`{"status": "ERROR", "message": "..."}`
Namecheap	Always 200	`Status="ERROR"` and `<Error Number="...">`

The same refusal in each:

JSON

{"SetDnsResponse": {"ResponseCode": "-1", "Status": "error", "Error": "This API key doesn't work for nameservers."}}
{"detail": "This API key doesn't work for nameservers.", "data": []}
{"success": false, "errors": [{"code": 1004, "message": "This API key doesn't work for nameservers."}], "messages": [], "result": null}
{"code": "ACCESS_DENIED", "message": "This API key doesn't work for nameservers."}
{"status": "ERROR", "message": "This API key doesn't work for nameservers."}

XML

<ApiResponse Status="ERROR" xmlns="http://api.namecheap.com/xml.response">
  <Errors>
    <Error Number="2011280">This API key doesn't work for nameservers.</Error>
  </Errors>
</ApiResponse>

In Dynadot style, errors before a command runs (key, command name, rate limit) use a plain Response object: {"Response": {"ResponseCode": "-1", "Error": "invalid key"}}. Test str(ResponseCode) == "0" for success.

When you match on texts in code, match on the start: the part after a semicolon or colon (a name, a number, a hint) varies.

The HTTP column below is for the four styles that use status codes. Cloudflare's numeric codes and Namecheap's error numbers are on their pages.

Key, command and limits#

Error	HTTP	Cause and fix
`invalid key`	401 (Cloudflare and Porkbun: 403)	Wrong key or secret, a revoked key, or a call from an IP address the key is not locked to. Check the key and where you call from.
`incorrect command name`	404	Unknown command or path. Check the spelling against the style's reference.
`command not available on this account`	403	A call outside DNS records (`register`, `renew`, contacts, transfers, ...). Not possible with MailDNS.
`XML is not supported: call /api3.json`		Dynadot style only: you called `/api3.xml`.
`too many requests; retry in 0.4 seconds`	429	Over 10 requests per second. Wait `Retry-After` seconds and send the same call again.
`another change to this domain is still running; retry in a few seconds`	429	An earlier change to the same root domain took more than 60 seconds. Nothing was changed. Retry.

Nameservers#

Error	HTTP	Cause and fix
`This API key doesn't work for nameservers.`	403	A nameserver change or an NS record, in any style. No key can do this. Don't retry.

Domains and names#

Error	HTTP	Cause and fix
`domain parameter not entered`	422	The call names no domain.
`could not find domain in your account`	404	The domain is neither one of your key's hosts nor the root of one. List your hosts to check.
`domain not found`	404	A host lookup (`/api/v1/domains/{domain}`, `/v1/domains/{domain}`) with a name that is not one of your hosts.
`www.example.com is not one of your hosts`	403	A record name outside your hosts. Records go at or under a host.
`main records of example.com are not on your account; ...`	403	A record at the root domain (a main record, or `@`) when your host is a name inside it. Address the host, or use a subhost. See Hosts.
`subdomain0 is empty`		Dynadot style: a `subdomain{n}` that is empty or `@`. For a record at the domain, use `main_record{n}`.

Records#

Error	HTTP	Cause and fix
`no dns record entered`	422	A write with no records in it.
`record type SRV is not allowed (allowed: A, AAAA, CNAME, MX, TXT)`	422	Only these five types. (NS gets the nameserver answer above.)
`empty value for TXT record`	422	A record with no value.
`TXT value is 2310 characters (max 2048)`	422	TXT values are limited to 2,048 characters.
`TXT value must be printable ASCII`	422	No line breaks, tabs or non-ASCII characters in TXT values.
`invalid MX priority: 'ten'`, `MX priority out of range: 70000`	422	MX priority is a whole number from 0 to 65535.
`invalid ttl: 'one hour'`	422	TTL is a whole number of seconds.
`invalid IPv4 address: ...`, `invalid IPv6 address: ...`	422	`A` takes an IPv4 address, `AAAA` an IPv6 address.
`invalid name: ...`	422	A name with characters DNS does not allow. Letters, digits, `-` and `_`, separated by dots.
`51 records under one host (max 50)`	422	A host holds at most 50 records, at and under it.
`a CNAME cannot share a name with other records (mail)`, `only one CNAME per name`	422	Move the other records first. (Spaceship style: `"force": true` replaces them.)

Cloudflare style answers record errors with HTTP 400, code 1004, as Cloudflare does.

When MailDNS can't make the change#

Error	HTTP	Cause and fix
`example.com has expired; records can't be changed`	503	The root domain has expired. Its records can't be changed until it is renewed. Tell whoever issued your key.
`example.com is not active at its registry (...); records can't be changed`	503	The root domain is on hold or otherwise not active. Tell whoever issued your key.
`this domain is temporarily unavailable; ...`	503	The domain can't be changed right now. Retry in a few minutes.
`changes to this domain are paused; ...`	503	Changes to this domain are on hold. Tell whoever issued your key.
`the change could not be saved and nothing was changed; ...`	503	The change was rolled back as a whole. Retry later.
`DNS for this domain is not served by MailDNS, so records can't be changed here`	503	This domain's DNS is hosted somewhere MailDNS doesn't write to. Tell whoever issued your key.
`internal error`	500	Unexpected. Retry once; if it repeats, tell whoever issued your key.

The texts ending in ... carry a short note after the semicolon. It never changes what you should do.

Retrying safely#

Every write is safe to send twice:

Adds (Dynadot set_dns2 with add_dns_to_current_setting=1, Spaceship PUT, Cloudflare POST, GoDaddy PATCH, Porkbun /dns/create) skip records that are already there.
Replaces (Dynadot set_dns2 without the add flag, GoDaddy PUT, Namecheap setHosts) end in the same state however often you send them.
Deletes: Spaceship's DELETE ignores records that are already gone. Deletes by id or by name (Cloudflare, GoDaddy, Porkbun) answer "not found" for a record that is already gone: treat that as done.

So after a timeout or a dropped connection, send the same call again. Retry automatically only the rate limit, the busy error and 503s, with a pause. Errors about the key, a name, a record or nameservers will fail the same way every time: fix the call instead.