Error handling & retries

When a request fails, the API returns an HTTP status and an error response with the same structure on every endpoint, including an error code you can match on programmatically.

Response format

Every error follows the same JSON structure. Match on the code field to handle specific cases in your code:

{
  "success": false,
  "data": null,
  "error": {
    "code": "INSUFFICIENT_CREDITS",
    "message": "Insufficient credits: 0 available, 1 required"
  },
  "metadata": {
    "requestId": "00bc3fa0-348f-4955-a1c1-3c7c91234568",
    "executionTimeMs": 3
  }
}

Error reference

Search filter validation

The search endpoints validate every filter before running the query. A rejected request returns 422, costs 0 credits, and never reaches the database. Without this check, a filter we cannot honor would return an empty page that looks like a legitimate "no results".

error.details.errors always lists every problem found, so one round trip is enough to fix a whole payload.

{
  "success": false,
  "data": null,
  "error": {
    "code": "INVALID_FILTER_VALUE",
    "message": "\"Technology\" is not an accepted value for \"industry\". Did you mean \"Technology, Information and Internet\", \"Technology, Information and Media\"? This filter is matched exactly, so an unlisted value can never return a result.",
    "details": {
      "field": "industry",
      "value": "Technology",
      "reason": "not_in_accepted_values",
      "suggestions": ["Technology, Information and Internet", "Technology, Information and Media"],
      "documentation": "https://docs.reversecontact.com/guides/industries"
    }
  }
}

Values are compared tolerantly before being rejected: case, surrounding spaces, accents and & versus and are normalized for you. Only an unknown value is refused.

When to retry

These statuses are safe to retry, and they cost 0 credits:

• 429: you've hit a rate limit. Wait the number of seconds in error.details.retryAfter, then retry. With KEY_CREDIT_LIMIT_REACHED, that wait runs until 00:00 UTC or the 1st of the month: pause the work rather than retrying in a loop.
• 500, 502, 503 and 504: a temporary issue on our side or at a provider we rely on. Retry with exponential backoff (below), and stop after a few attempts, for example 5, then alert. Incidents are posted on status.reversecontact.com, where you can subscribe to updates by email, Slack, webhook or RSS.
• 409 with IDEMPOTENCY_KEY_IN_USE: a request with the same Idempotency-Key is still being processed. Wait the Retry-After seconds, then retry with the same key. A 409 JOB_RESULTS_NOT_READY asks you to wait for the job instead, and a 409 JOB_NOT_CANCELLABLE or 409 JOB_RESULTS_FORMAT_UNAVAILABLE is final.

All other errors (400, 401, 402, 403, 404, 410, 413, 422, 451) require a change to your request, your key or your credit balance before retrying.

Find Email and Find Phone debit credits when their job is created, and Bulk enrichment reserves them when it creates its job. Before you retry one of them after a timeout or a dropped connection, make sure the request carries an Idempotency-Key: a retry with the same key returns the first response instead of starting a second lookup or job. See Find Email.

Wait a little longer between each retry to give the server time to recover:

const delay = Math.min(1000 * 2 ** attempt, 15000)
const jitter = Math.floor(Math.random() * 250)
await new Promise((r) => setTimeout(r, delay + jitter))

delay = min(1 * 2 ** attempt, 15)
jitter = random.uniform(0, 0.25)
time.sleep(delay + jitter)

Timeouts and aborted requests

Set your client timeout to at least 45 seconds on the search and count endpoints, and 60 seconds on prompt search. When a search runs out of time, we answer with a JSON 504 before those limits, and it costs 0 credits. A shorter client timeout can cut the connection just before that answer arrives.

Closing the connection does not cancel the request. It keeps running on our side and can still be billed, even though you never receive the page. A retry after an abort can then bill the same page twice, so raise a timeout that fires too early rather than aborting and retrying.

Credits and errors

All error responses (401, 402, 403, 409, 410, 413, 422, 429, 451, 500, 502, 503, 504) cost 0 credits.

The 404 status is the only exception: some endpoints charge credits when the lookup was performed but no result was found. See API pricing for the full breakdown.