Search the docs

Find a page, a section, or an endpoint.

Sign inGet started

Errors

The envelope, the codes, and what each one means you should do.

A failure is always the same shape, with an HTTP status that means the same thing as the code inside it.

json
{
"error": {
  "code": "validation",
  "message": "Enter only the part before the @.",
  "field": "local_part"
}
}

message is written for a person and is safe to show one. It never carries a stack, a DNS response code or a provider's wording — if you are surfacing API errors in your own interface, this is the string to use.

The codes

| Code | Status | What it means | | ----------------- | ------ | --------------------------------------------------- | | validation | 400 | The request is malformed. field says where. | | unauthenticated | 401 | No key, or a key that has been deleted. | | forbidden | 403 | A real resource that is not yours. | | not_found | 404 | No such resource — or one that is not yours. | | conflict | 409 | It already exists, or something else changed first. | | entitlement | 402 | Your plan does not include this. | | abuse_blocked | 403 | The account is paused pending review. | | rate_limited | 429 | Too many requests. See the headers below. | | unavailable | 503 | Ours, and temporary. Retry. | | internal | 500 | Ours, and unexpected. |

forbidden and not_found deliberately return the same sentence. Confirming that a resource exists but belongs to somebody else is itself a leak, so the API does not.

Rate limit headers

Every response carries them, not just the ones that failed, so a client can pace itself rather than discover the limit by hitting it.

http
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 118
X-RateLimit-Reset: 1757760060

Reset is unix seconds. A 429 also carries Retry-After.