# Handle errors (https://developer.godaddy.com/en/docs/api-users/errors) *** title: Handle errors description: Error response shape, status code semantics, and retry guidance. keywords: 400 401 403 404 422 429 500, UNABLE\_TO\_AUTHENTICATE, requestId, error envelope, exponential backoff, idempotency key agentNotes: scopes: \["Any — applies to all API operations"] rateLimit: "N/A (informational reference)" failureRecovery: "Match the 'code' field, not HTTP status, for programmatic handling. 4xx errors are client-fixable (check input, scopes, payment profile). 5xx errors are safe to retry with exponential backoff. 429 means wait for Retry-After header." related: guides: * title: "Handle rate limits" href: "/docs/api-users/rate-limits" * title: "Authentication" href: "/docs/api-users/auth" * title: "Set up a payment profile" href: "/docs/api-users/payment-profile" apis: * title: "Domains v3 reference" href: "/docs/references/rest/domains/v3" * title: "Domains v1 reference" href: "/docs/references/rest/domains/v1" *** ## Overview GoDaddy REST APIs return a consistent error envelope. Every error response includes a stable `code` field for programmatic handling, and optionally field-level validation details. This page covers the response shape, status code semantics, and retry guidance for the Domains and Auctions APIs. ## Error response shape `Error` schema (used for 4xx and 5xx responses): ```json { "code": "INVALID_BODY", "message": "Request body did not match the expected schema.", "fields": [ { "path": "contactRegistrant.email", "code": "INVALID_FORMAT", "message": "Value must be a valid email address." } ] } ``` | Field | Required | Description | | ---------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | | `code` | Yes | Stable, machine-readable error code. Match on this for programmatic handling. | | `message` | No | Human-readable message. May change between releases. | | `fields[]` | No | Per-field validation details when the error is body- or query-scoped. Each entry has its own `path` (JSONPath into the request), `code`, and `message`. | `ErrorLimit` extends `Error` with one additional field for rate-limit (`429`) responses: | Field | Required | Description | | --------------- | -------- | ----------------------------------------------------------------------------------------------------------------- | | `retryAfterSec` | Yes | Seconds the caller should wait before retrying the same operation. Mirrored in the `Retry-After` response header. | ## Status codes | Status | Meaning | Caller action | | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------- | | `400 Bad Request` | Request was malformed (missing required field, invalid query parameter format). | Fix the request. Inspect `fields[]` for specifics. | | `401 Unauthorized` | `Authorization` header missing, malformed, expired, or revoked. | Re-authenticate. See [Authentication](https://developer.godaddy.com/docs/api-users/auth). | | `403 Forbidden` | Authenticated but unauthorized — usually a missing scope or insufficient role. | Issue a token with the required scope, or escalate the calling principal's authorization. | | `404 Not Found` | The path doesn't exist, or the addressed resource (domain, contact, record) isn't visible to this caller. | Verify the path and confirm the caller owns or can access the resource. | | `409 Conflict` | The request conflicts with current state (e.g. registering a name already taken; updating a record set that's mid-transfer). | Re-read state and retry only after resolving the conflict. | | `422 Unprocessable Entity` | Request was syntactically valid but semantically rejected (e.g. invalid registrant data, TLD-specific constraint failure, `NO_PAYMENT_PROFILE`). | Inspect `code` and `fields[]`. For missing billing, see [Set up a payment profile](https://developer.godaddy.com/docs/api-users/payment-profile). | | `429 Too Many Requests` | Rate limit exceeded. Response is shaped as `ErrorLimit`. | Wait `retryAfterSec` seconds, then retry. Go to [Handle rate limits](https://developer.godaddy.com/docs/api-users/rate-limits) for strategies. | | `5xx Server Error` | Upstream registry or service issue. | Retry idempotent operations with exponential backoff. See [Retry semantics](#retry-semantics) for non-idempotent ones. | ## Retry semantics The following sections describe the retry semantics for read and write operations using Domains API endpoints. The same retry semantics apply across GoDaddy REST APIs. Endpoint paths will vary by API. ### Read operations All `GET` operations are safe to retry. Domains API examples: * `GET /v3/domains/check-availability` — availability check * `GET /v1/domains` — list your domains * `GET /v1/domains/{domain}` — domain detail * `GET /v1/domains/{domain}/records` — DNS records ### Write operations Most writes can be retried after a 5xx, but **the API doesn't support an `Idempotency-Key` request header** — neither v1 nor v2 specs declare one. This affects retry strategy on a few specific operations: | Operation | Retry-safe? | | --------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `POST /v1/domains/purchase` | **Not idempotent without external coordination.** A retry can result in a duplicate registration if the first attempt actually succeeded server-side. Pair every retry with a fresh `GET /v1/domains/available` and a state check via `GET /v1/domains/{domain}`. | | `POST /v1/domains/{domain}/renew` | Idempotent within a billing cycle in practice — the registry rejects duplicates — but treat the same as `purchase`: confirm state before retrying. | | `POST /v1/domains/{domain}/transfer` | Same as `purchase`. | | `PUT /v1/domains/{domain}/records` (replace) | Idempotent by shape — replaying the same request produces the same record set. | | `PATCH /v1/domains/{domain}/records` (add) | **Not idempotent** — repeated calls add duplicate records. | | `DELETE /v1/domains/{domain}/records/{type}/{name}` | Idempotent — deleting an already-deleted record is a no-op. | ## Programmatic error handling Match on `code`, not `message`. Codes are stable across releases; messages may be refined. The codes in the example below are specific to the Domains API. Check your API's OpenAPI specification for its error codes. ```js const res = await fetch(url, { headers }); if (!res.ok) { const err = await res.json(); switch (err.code) { case "DOMAIN_NOT_AVAILABLE": // someone else registered the name first break; case "BILLING_DECLINED": // payment method failed — surface to user break; case "NO_PAYMENT_PROFILE": // no billing method on account — see payment profile setup break; default: // log err.code and err.fields for debugging throw new Error(err.code + ": " + err.message); } } ``` Reference: the `Error` and `ErrorLimit` schemas are defined in the OpenAPI specification.