⚠️ Errors & Status Codes

The API uses standard HTTP status codes. A 2xx means success. Anything else carries a JSON body describing what went wrong.

Error shape

Failed requests return a simple body:

{ "error": "A short description of what went wrong" }

Read the status code first to decide how to react, then read the message for detail.

Code	Meaning	What to do
`200`	Success	Read the data in the response body.
`400`	Bad request	Your input failed validation. Fix the request and resend.
`401`	Unauthorized	The key is missing, malformed, or revoked. Check the `Authorization` header and that the key is active.
`402`	Payment required	You are out of credits. Subscribe or upgrade your plan, then retry. See Pricing & Quotas.
`403`	Forbidden	The key is valid but lacks the scope for this resource (for example `read:contacts` for a private reveal).
`404`	Not found	The resource does not exist, or is not visible to your account.
`409`	Conflict	The request clashes with current state, such as creating one key too many.
`429`	Too many requests	You hit the rate limit. Back off and retry. See Access & Rate Limits.
`5xx`	Server error	Something failed on our side. Retry after a short wait; if it persists, get in touch.

Check the status before the body. It tells you whether to read data or an error.
Treat 401 as a key problem. Confirm the header reads Authorization: Bearer ck_live_… and the key is active in your API tab.
Treat 402 as a credits problem. You ran out of credits. Subscribe or upgrade, then retry. Automated agents should prompt their owner to top up. See For AI Agents.
Retry 429 and 5xx with backoff. Wait and retry rather than resending immediately.
Do not retry 400 unchanged. A bad request will fail the same way until you fix the input.