Error Handling

All public data API errors use a JSON envelope with a machine-readable code and a request id.

{
  "error": {
    "code": "MACHINE_READABLE_CODE",
    "message": "Human-readable explanation",
    "status": 429,
    "request_id": "req_abc123...",
    "details": {}
  }
}

details is optional and depends on the error.

Public data API errors

Code	HTTP	Meaning
`MISSING_API_KEY`	401	The request did not include `X-Api-Key`.
`INVALID_API_KEY`	401	The key is unknown, inactive, or invalid.
`INVALID_PARAMETERS`	400	Query parameters failed public endpoint validation.
`PRODUCT_NOT_ALLOWED`	403	The authenticated account cannot access the requested API family.
`NOT_FOUND`	404	The requested resource was not found.
`QUOTA_EXCEEDED`	429	Request-time quota enforcement rejected the request.
`RATE_LIMITED`	429	The request exceeded burst or route protection limits.
`INTERNAL_ERROR`	500	The API failed unexpectedly.

Parameter validation

Public Address endpoints validate required and constrained query parameters before running a search. Invalid requests return 400 INVALID_PARAMETERS. For example, calling autocomplete without q returns the standard error envelope with field-level details:

{
  "error": {
    "code": "INVALID_PARAMETERS",
    "message": "Invalid query parameters",
    "status": 400,
    "request_id": "req_abc123...",
    "details": {
      "q": ["Required"]
    }
  }
}

details uses field names as keys. Each value is an array of validation messages for that field. The exact message text can change with validation library updates, so clients should branch on error.code, error.status, and the presence of a field key rather than matching message strings.

Private or forward-contract errors

These codes can appear on private console/account routes or are reserved for forward-compatible contracts. They are listed here so integrations can classify them if encountered, but they are not all public data API outcomes.

Code	HTTP	Meaning
`KEY_LIMIT_EXCEEDED`	403	A console key-management action would exceed the current key limit.
`UNAUTHORIZED`	401	A private route is missing a valid Clerk session.
`ORG_REQUIRED`	403	A private route needs an active Clerk organization.
`INVALID_SIGNATURE`	400	A webhook signature did not verify.
`SERVICE_UNAVAILABLE`	503	A dependency is unavailable or a circuit is open.

Retry guidance

Retry RATE_LIMITED after Retry-After when that header is present.
Do not automatically retry QUOTA_EXCEEDED; direct the user to account billing or support.
Retry SERVICE_UNAVAILABLE with exponential backoff and jitter.
Do not retry MISSING_API_KEY, INVALID_API_KEY, INVALID_PARAMETERS, or PRODUCT_NOT_ALLOWED without changing credentials, parameters, or account access.
Do not retry NOT_FOUND for the same resource id unless upstream data has changed or the id came from stale client state.
Treat INTERNAL_ERROR as retryable only with bounded retries.

Request-id tracing

Every response includes X-Request-Id. Error responses include the same value as error.request_id. When contacting support, include:

the request id;
endpoint path and method;
timestamp;
account or organization name;
sanitized client context.

Do not send API keys, request bodies containing sensitive user data, or raw customer data in support messages.

Getting Started

Address API

SDKs

Public data API errors

Parameter validation

Private or forward-contract errors

Retry guidance

Request-id tracing

​Public data API errors

​Parameter validation

​Private or forward-contract errors

​Retry guidance

​Request-id tracing

Public data API errors

Parameter validation

Private or forward-contract errors

Retry guidance

Request-id tracing