Errors
Errors use standard HTTP status codes and one JSON shape, with a stable code you can branch on.
Error shape
{
"error": {
"code": "insufficient_credits",
"message": "Not enough credits for this request."
}
}Branch on code, not on message: messages are written for people and may change.
Codes
| Status | Code | Meaning |
|---|---|---|
| 400 | invalid_request | A field or filter is wrong, or the body is not valid JSON. The message names the field. |
| 401 | unauthorized | The API key is missing, revoked or mistyped. |
| 402 | insufficient_credits | Not enough credits for a paid call. Nothing was charged; top up and retry. |
| 404 | not_found | No such record, or no contact details could be found. Nothing was charged. |
| 409 | not_revealed | The call needs a contact you have revealed first, such as mobile numbers or personality. |
| 429 | rate_limited | Too many requests in a short time. The message says how many seconds to wait. |
| 429 | daily_limit | Today's cap on new searches is reached. Cached searches still work; it resets within 24 hours. |
| 503 | unavailable | The data provider is briefly unavailable. Retry with backoff. |
| 500 | internal | Something went wrong on our side. Retry; if it keeps happening, contact support. |
Retrying
Retry 429 rate_limited, 503 and 500 with exponential backoff. Do not retry 400, 401, 402 or 409 without changing something first. A failed call is never charged.
Over MCP, a tool that fails returns a normal result with isError: true and the same { error: { code, message } } body, so the assistant can read it and adjust.