Errors
HTTP status codes and stable error codes returned by the API.
Errors are returned as { "error": "code" } with a matching HTTP status. Codes are stable and safe to match on in client code.
| Status | Example error code | Meaning |
|---|---|---|
| 400 | zone_name_type_content_required | The request body is missing a required field or is otherwise invalid. |
| 401 | invalid_token | The bearer token is missing, malformed, revoked, or expired. |
| 403 | forbidden / read_scope_token | Authenticated, but not allowed to perform this action (role, scope, or domain pin). |
| 403 | token_scope_restricted | A zone-pinned token called a path outside the Domains, DNS, external-dns, and tokens surface. |
| 403 | domain_pin_required | Token minting without a domain pin — required for non-admins and for all zone-pinned callers. |
| 404 | not_found | The resource does not exist in your organization. |
| 405 | method_not_allowed | The HTTP method is not supported on this route. |
| 409 | cname_conflict / managed_record | The change conflicts with existing state — a clashing DNS record, or a system-managed record that needs ?force=true. |
| 502 | powerdns_unavailable | A downstream dependency (the DNS provider) failed. Safe to retry. |