Get started

Errors

Errors use standard HTTP status codes and one JSON shape, with a stable code you can branch on.

Error shape

Error body
{
  "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

Error codes
StatusCodeMeaning
400invalid_requestA field or filter is wrong, or the body is not valid JSON. The message names the field.
401unauthorizedThe API key is missing, revoked or mistyped.
402insufficient_creditsNot enough credits for a paid call. Nothing was charged; top up and retry.
404not_foundNo such record, or no contact details could be found. Nothing was charged.
409not_revealedThe call needs a contact you have revealed first, such as mobile numbers or personality.
429rate_limitedToo many requests in a short time. The message says how many seconds to wait.
429daily_limitToday's cap on new searches is reached. Cached searches still work; it resets within 24 hours.
503unavailableThe data provider is briefly unavailable. Retry with backoff.
500internalSomething 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.