Errors
Every failure returns the same two fields.
{
"error": "machine_code",
"message": "human readable"
}
The message wording can change, so do not depend on it.
Finding nothing is not a failure
A miss answers with HTTP 200 and found false.
Codes
| Status | Code | Meaning | What to do |
|---|---|---|---|
| 400 | validation_error |
The request was invalid. | Check the request against the endpoint's field table. Retrying the same request will not help. |
| 401 | invalid_api_key |
The X-API-Key header is missing, wrong, or belongs to a revoked key. | Check the header name and the key. |
| 402 | out_of_credits |
Your balance does not cover the call. Nothing was charged and no lookup ran. | Top up or wait for your next renewal. |
| 429 | rate_limited |
Too many calls to this endpoint on this key. | Wait the number of seconds in the Retry-After header, then retry. |
| 503 | data_temporarily_unavailable |
A source we depend on did not answer in time. Never charged. | Retry later. The same request will usually succeed. |
| 500 | internal_error |
A bug on our side. Never charged. | Retry later, it may resolve itself. If it keeps failing, send us the request. |