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):

{
  "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.
`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.
`429 Too Many Requests`	Rate limit exceeded. Response is shaped as `ErrorLimit`.	Wait `retryAfterSec` seconds, then retry. Go to Handle rate limits for strategies.
`5xx Server Error`	Upstream registry or service issue.	Retry idempotent operations with exponential backoff. See Retry semantics for non-idempotent ones.

Retry semantics

The following sections describe the retry semantics for read and write operations.

Read operations

All GET operations on the Domains API are safe to retry. 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.

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.

Agent & Automation Notes

ScopesAny — applies to all API operations

Rate limitN/A (informational reference)

On failureMatch 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.

API References

Guides

Last updated on

Handle errors