Error codes

The HTTP status and error codes the API returns for zones, records, delegation checks, batches, merges and the email check.

Errors come as JSON with a stable code, a human-readable message and, for validation errors, the field at fault:

{"error": {"code": "invalid", "message": "must be between 60 and 86400 seconds", "field": "ttl"}}

Program against code, not message. The CLI exits with 1 on errors, 2 on usage errors and 3 on a version conflict.

Request and permission errors

Status	Code	When
400	`bad_request`	Malformed JSON, unknown fields, bad `If-Match` or `dry_run` values
401	`unauthorized`	Missing, invalid, expired or revoked token
403	`forbidden`	The role or scope does not allow the action (for example a `readonly` token writing records, or a domain-scoped token adding zones)
403	`token_scope`	A purge-only token called anything other than the cache purge
404	`not_found`	The zone, record or resource does not exist or is outside your scope
413	`too_large`	A BIND zone file over 1 MiB

Status	Code	When
422	`invalid`	A field is not valid: see `field` and `message`. Examples: an unsupported record type, a TTL outside 60–86,400, a priority on an `A` record, a proxied wildcard, a coexistence rule, a public suffix as zone name, more than 500 operations in a batch (`field` names the operation, such as `create[2].content`)
422	`reason_required`	A configuration change without `X-Change-Reason` (1–500 characters)

Status	Code	When
403	`zone_limit`	The organization has reached its domain limit. Delete unused domains or ask support to raise it
409	`zone_exists`	The domain is already added in OpenWAF
409	`zone_overlaps`	The domain is a parent or a subdomain of a domain managed by another organization or client
409	`zone_not_external`	An external-only operation (such as `GET …/hosts`) on a delegated zone
409	`conflict`	The zone is disabled, the operation does not apply to an external zone (for example importing records), or a name is already taken
409	`zone_merged`	The zone was merged into another and is read-only
409	`merge_not_equivalent`	A merge would change what some name serves, or cannot be expressed; see `plan.problems`
409	`merge_not_reversible`	The parent zone changed after the merge
409	`missing_certs`	The change would leave a site without a valid certificate; `hostnames` lists them
412	`version_conflict`	`If-Match` (or `expected_version`) does not match the zone's current version; `current_version` has it
428	`if_match_required`	A revert without `If-Match`

Status	Code	When
502	`dns_backend`	The DNS servers rejected the change; nothing was applied. Retry, and contact support if it persists
502	`dns_out_of_sync`	The change was rolled back because it could not be published; contact support
502	`dns_unavailable`	The email check could not get answers from public DNS
503	`busy`	Too many email checks running; retry in a few seconds
503	`unavailable`	The feature is temporarily unavailable

Status	Code	When
409	`client_has_zones`	Deleting a client that still has domains
409	`host_taken`	The dashboard domain or nameserver name belongs to another organization
409	`conflict`	Removing or demoting the last owner, or a client name already in use