Skip to content
Get started

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.

422 Unprocessable Entity
{
  "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.codestring

A stable, machine-readable code. Branch on this, not on the message.

error.messagestring

A sentence you can log or show to a developer.

error.fieldstring

The request field at fault. Present on invalid_input.

meta.request_idstring

Quote this when you contact support.

Status and error codes

CodeHTTPMeaningRetry
invalid_input422A field is missing or malformed. The field property names it.No. Fix the request.
unauthorized401The key is missing, malformed or revoked.No. Check the key.
insufficient_credits402Your 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_required403The product needs a use-case review before it is switched on for your account.After approval.
not_found404The endpoint or bulk job does not exist.No.
rate_limited429Too many requests for this key.Yes, after Retry-After.
internal_error500Something failed on our side.Yes, with backoff.
source_unavailable503An 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.