Skip to main content

​
HTTP status codes

StatusMeaningRetryable
400 Bad RequestInvalid request parameters (e.g. missing name)No
401 UnauthorizedAPI key is missing, invalid, or revokedNo
403 ForbiddenAPI key lacks permission for this operationNo
404 Not FoundThe requested search ID does not existNo
429 Too Many RequestsRate limit exceededYes — after Retry-After seconds
500 Internal Server ErrorUnexpected server errorYes — with backoff
All error responses follow this shape: 
{ "error": "Human-readable error message" }

​
Error codes in search responses

When a data source encounters an error mid-search, the errors object in the response body contains structured error details: 
{
  "errors": {
    "registry": {
      "code": "TIMEOUT",
      "message": "Business registry request timed out after 40 seconds",
      "retryable": true
    }
  }
}
CodeDescription
TIMEOUTThe data source did not respond in time
RATE_LIMITEDThe upstream service rate-limited the request
NOT_FOUNDNo records found for this query
INVALID_INPUTThe query could not be processed by this source
UPSTREAM_ERRORThe upstream service returned an error
PARSE_ERRORThe upstream response could not be parsed
AUTH_ERRORAuthentication with the upstream service failed
UNAVAILABLEThe upstream service is temporarily down
UNKNOWNAn unexpected error occurred
When retryable is true, re-running the search may succeed.

​
Partial failures

A search with some errors still returns all data from the sources that succeeded. The top-level status will be completed-with-errors rather than completed. 
{
  "meta": {
    "status": "completed-with-errors",
    ...
  },
  "businesses": [ ... ],  // succeeded
  "regulatory": { ... },  // succeeded
  "errors": {
    "sanctions": {
      "code": "UNAVAILABLE",
      "message": "Sanctions service temporarily unavailable",
      "retryable": true
    }
  }
}
Always check both meta.status and the errors object. A completed-with-errors response still contains valid data — only the listed sources failed.