Handle errors

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 GoDaddy REST APIs — including the Domains, Auctions, and Hosting APIs.

The Email API uses a different envelope, documented in Email error envelope.

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."
    }
  ]
}

ErrorLimit extends Error with one additional field for rate-limit (429) responses:

Email error envelope

The Email API's Error schema uses different field names than the code/message/fields[] envelope above:

{
  "name": "INVALID_INPUT",
  "correlationId": "req-abc-123",
  "message": "The provided request is invalid.",
  "details": [
    {
      "field": "/emailAddress",
      "issue": "PATTERN_VIOLATION",
      "location": "body",
      "description": "Email address must be a valid address on a domain owned by the authenticated account."
    }
  ]
}

Email's 429 response doesn't include a retryAfterSec field — check the Retry-After response header instead.

Status codes

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 Domains writes can be retried after a 5xx, but the Domains 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:

Async write operations

The Hosting API returns 202 Accepted for most write operations. The caller must poll a status endpoint until the operation reaches a terminal state. Retry semantics differ from synchronous writes:

Programmatic error handling

Match on code, not message. Codes are stable across releases; messages might be refined. The codes below are specific to the Domains API.

Check your API's OpenAPI specification for its error codes.

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.

Shopping API error responses

The Shopping API usually maps errors to HTTP status codes. A 2xx response can also contain an error envelope, so check the status and messages[].code on every response.

{
  "ucp": { "version": "2026-04-08", "status": "error" },
  "messages": [
    {
      "type": "error",
      "code": "validation_error",
      "content_type": "plain",
      "content": "line_items[0].item.id is required."
    }
  ]
}

Common codes include invalid_request, validation_error, product_not_found, checkout_not_found, order_not_found, item_not_found, and unsupported_currency.

const res = await fetch(url, { headers });
const body = await res.json();

// Check the HTTP status and the error marker.
if (!res.ok || body?.ucp?.status === "error") {
  const code = body?.messages?.[0]?.code;
  switch (code) {
    case "validation_error":
      // fix the line item and retry
      break;
    case "item_not_found":
      // choose a current purchasable variant
      break;
    default:
      throw new Error(`Shopping API error: ${code}`);
  }
}

Go to About the Shopping API for the Shopping status and code reference.

Last updated on