Errors
Errors use standard HTTP status codes and one JSON shape. A request that returns an error is never charged.
Error shape
A failed request returns success: false and an error object in place of data. The meta block is still there, with credits_used at 0.
{
"success": false,
"error": {
"code": "invalid_input",
"message": "Enter a phone number with 7 to 15 digits, including country code.",
"field": "phone_number"
},
"meta": {
"credits_used": 0,
"credits_remaining": 999,
"cached": false,
"request_id": "req_8f3a2c1e9b7d"
}
}error.codestringA stable, machine-readable code. Branch on this, not on the message.
error.messagestringA sentence you can log or show to a developer.
error.fieldstringThe request field at fault. Present on invalid_input.
meta.request_idstringQuote this when you contact support.
Status and error codes
| Code | HTTP | Meaning | Retry |
|---|---|---|---|
invalid_input | 422 | A field is missing or malformed. The field property names it. | No. Fix the request. |
unauthorized | 401 | The key is missing, malformed or revoked. | No. Check the key. |
insufficient_credits | 402 | Your credits are used up and pay as you go is off or at its limit. Nothing was run. | After credits renew or the limit changes. |
approval_required | 403 | The product needs a use-case review before it is switched on for your account. | After approval. |
not_found | 404 | The endpoint or bulk job does not exist. | No. |
rate_limited | 429 | Too many requests for this key. | Yes, after Retry-After. |
internal_error | 500 | Something failed on our side. | Yes, with backoff. |
source_unavailable | 503 | An upstream source did not answer in time. | Yes, with backoff. |
A no-match is not an error
When a lookup runs but finds nothing, the response is 200 with success: true and a result that says so, such as match_found: false. On products priced per match, meta.credits_used is 0.
Retrying
Retry 429, 500 and 503 with exponential backoff and jitter, starting at one second. Do not retry other 4xx errors: the request needs to change first.
Rate limiting has its own page: see rate limits for the headers and a backoff example.