Errors
Every error code of the findbytown API and MCP server, with its HTTP status and what to do.
An error has the HTTP status below and this body. error is stable: build on it, not on message, whose wording may change. Quote requestId when you write to us; it is also in the X-Request-Id header.
{
"error": "quota_exhausted",
"message": "Monthly reveal quota exhausted.",
"details": {
"resetAt": "2030-01-01T00:00:00.000Z"
},
"requestId": "00000000-0000-4000-8000-000000000000"
}A 429 also carries Retry-After, in seconds. A 401 carries WWW-Authenticate: Bearer.
| Code | HTTP status | Meaning |
|---|---|---|
| validation_error | 400 | A parameter is missing or has the wrong form. details names it. |
| unknown_parameter | 400 | A query parameter is not one this endpoint knows, usually a typing mistake. details names it. |
| use_reveal_endpoint | 400 | You sent reveal= on a read. Reads never spend quota: use the reveal endpoint. |
| bad_id | 400 | The company id is not a positive integer. |
| missing_api_key | 401 | No Authorization header, or an empty one. |
| invalid_api_key | 401 | The key does not exist or has been revoked. |
| quota_exhausted | 402 | No reveals left this period. details holds the reset date. Reading stays available. |
| plan_without_api | 403 | The account's current plan does not include the API. Applies from the moment a plan ends. |
| suspended | 403 | The account is suspended. Its keys start working again if the suspension is lifted. |
| bad_origin | 403 | MCP only: the browser's Origin header is not one of our hosts. |
| not_found | 404 | No such company, or it was removed at its owner's request. |
| method_not_allowed | 405 | MCP only: GET and DELETE are not offered, use POST. |
| email_invalid | 409 | This company's email is marked invalid, so it cannot be revealed. Nothing was spent. |
| payload_too_large | 413 | MCP only: the request body is too large. |
| rate_limited | 429 | Too many requests this minute. Wait for the number of seconds in Retry-After. |
| budget_exhausted | 429 | You reached today's budget of distinct companies. Companies already seen today still pass. Retry-After says when it resets. |
| blocked | 429 | Access to company data is temporarily paused because of automated use, such as walking through ids. Retry-After gives the time left. Write to support if this is a mistake. |
| internal_error | 500 | Something went wrong on our side. Quote requestId when writing to support. |
| reveals_unavailable | 503 | Reveals are briefly unavailable and nothing was spent. Try again shortly. |