Error codes

Error codes

Structured errors

Every API error returns the same JSON shape: an error object with a stable code, a readable message, its type and HTTP status, whether it is retryable, the request_id and a docs_url. The request_id always matches the X-Request-Id response header, so include it when you contact support.

{
  "error": {
    "code": "INVALID_DOMAIN",
    "message": "Invalid domain format",
    "suggestion": "Use a registrable domain such as example.com",
    "type": "validation_error",
    "status": 400,
    "retryable": false,
    "request_id": "m5x7k2p-a9f3",
    "docs_url": "https://domscan.net/docs/check-availability"
  }
}

Error fields

Common error codes

These are the codes most clients need to handle. Some endpoints return more specific codes that follow the same rules; the full list with status, type and retry behavior is in the OpenAPI specification under x-domscan-error-codes. RATE_LIMIT_EXCEEDED is still accepted as an alias of RATE_LIMITED.

Retry guidance

• Retry only when retryable is true. For validation, authentication and permission errors, fix the request first.
• When retry_after or the Retry-After header is present, wait at least that many seconds before the next attempt.
• Otherwise use exponential backoff with jitter, for example 1, 2, 4 and 8 seconds, and stop after a few attempts.
• For batch and job creation, send an Idempotency-Key header so a retried request never creates a duplicate job.
• For other POST requests that charge credits, an Idempotency-Key header makes a retry return the stored response instead of charging again.

Compatibility

Since 10 October 2026 every endpoint uses this format. Fields that some endpoints already returned, such as credits_remaining, purchase_url, login_url, success or meta, are kept during a compatibility period, so existing integrations keep working. Read error details from the error object in new code.