Error Codes

Complete reference of error status codes and common error shapes. For error handling patterns, see Errors.

Response shape#

All errors return this shape:

json
{"detail": "Human-readable message"}

Or for structured errors:

json
{
  "detail": {
    "message": "...",
    "field": "...",
    "conflicts": [...]
  }
}

Validation errors (from Pydantic) return an array:

json
{
  "detail": [
    {"loc": ["body", "name"], "msg": "field required", "type": "value_error.missing"}
  ]
}

Code	Used when
`200`	GET, PATCH, POST returning a body
`201`	POST creating a resource (rare; usually `200`)
`204`	DELETE, or writes with no response body

Code	Use	Example
`400 Bad Request`	Malformed input the server can parse but not process	Invalid record type, malformed CIDR, unknown algorithm
`401 Unauthorized`	Missing or invalid credentials	No `X-API-Key`, expired JWT, invalid webhook signature
`403 Forbidden`	Authenticated but not allowed	Missing permission, IP whitelist mismatch, cross-tenant attempt on non-admin
`404 Not Found`	Resource doesn't exist (or you can't see it)	Wrong UUID, soft-deleted resource, tenant scoping
`409 Conflict`	Write conflicts with current state	Duplicate domain name, record coexistence rule, role already assigned
`413 Payload Too Large`	Request body exceeds limit	Bulk operation too large, file upload too large
`422 Unprocessable Entity`	Schema validation failed	Pydantic errors, missing required field
`429 Too Many Requests`	Rate limit hit	Exceeded API key rate limit; check `Retry-After`

Code	Use	What to do
`500 Internal Server Error`	Unhandled exception	Retry with backoff; if persistent, check health
`502 Bad Gateway`	Upstream dependency unreachable	Usually transient — retry
`503 Service Unavailable`	Maintenance or overload	Retry with backoff
`504 Gateway Timeout`	Upstream slow	Retry; check dashboards

Message	Cause
`Domain already exists`	409 — same name already in this tenant
`Invalid domain name`	400 — name fails RFC validation
`Unsupported domain type`	400 — bad `domain_type` value
`Domain not validated`	403 — trying to edit records on `pending_validation` zone
`Domain is deleted`	404 — zone is soft-deleted

Message	Cause
`Invalid record content`	400 — content doesn't match type format
`Record type not supported`	400 — unknown type
`Cannot create A record: CNAME exists at <name>`	409 — CNAME + A conflict
`DNAME cannot coexist with other records`	409 — DNAME rule violation
`Record already exists`	409 — duplicate `(name, type, content)`
`Invalid TTL`	400 — TTL must be positive integer

Message	Cause
`No DNS record found for <name>`	TXT record not published
`TXT record found but value doesn't match. Expected: ...`	Wrong TXT value
`Domain <name> does not exist in DNS`	NXDOMAIN at the TLD level
`No nameservers available for query`	Can't resolve authoritative NS
`DNS query timed out`	Authoritative NS unreachable
`Challenge expired`	Validation window passed

Message	Cause
`DNSSEC already enabled`	409 — trying to enable on a signed zone
`DNSSEC not enabled`	409 — trying to rotate a zone that isn't signed
`Unsupported algorithm`	400 — algorithm number not supported
`DS record does not match any KSK`	400 — confirm-ds-published with wrong DS
`KSK rotation in progress`	409 — can't start another rotation mid-rollover

Message	Cause
`Platform admin access required`	Caller isn't platform admin
`Admin access required`	Caller isn't tenant or platform admin
`<permission> permission required on this domain`	Missing specific permission
`IP not whitelisted`	API key IP whitelist blocks caller
`Access grant not found or expired`	Domain-level delegation missing

Message	Cause
`Missing X-API-Key header`	API-key-only endpoint called without header
`Invalid API key`	Key doesn't match or has been deleted
`API key revoked`	Key is `revoked` status
`API key expired`	`expires_at` passed
`Invalid JWT`	Token signature check failed
`Token expired`	JWT `exp` claim in the past
`Missing X-ScaiKey-Signature header`	Webhook call without signature
`Invalid webhook signature`	HMAC mismatch
`Webhook timestamp too old`	Timestamp outside 5-minute window

When rate limited (429), responses include:

text

1	`Retry-After: 60`

Value is seconds, or an HTTP date.

Healthy traffic also gets rate-limit headers:

text

1
2
3

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 42
X-RateLimit-Reset: 1714567890