Errors

Every error response uses the same JSON envelope, so you can handle failures with one code path.

Error response format

{
  "status": "error",
  "status_code": 400,
  "detail": "Human-readable description of what went wrong"
}

status — always "error" for a failed request.
status_code — mirrors the HTTP status code.
detail — a message string, or, for validation failures, an object keyed by the invalid field.

A validation error looks like this:

{
  "status": "error",
  "status_code": 400,
  "detail": { "company_id": "exactly one of company_id, company_link, company_name is required" }
}

Status codes

Code	Meaning	When it happens
`400`	Bad Request	Missing or invalid parameters, an unsupported filter for the chosen mode, a malformed LinkedIn URL, or a lookup that matched no record.
`401`	Unauthorized	Missing `Authorization` header or an invalid token. See Authentication.
`402`	Payment Required	Not enough balance to run the operation (`"Insufficient funds in the account."`). Top up in your billing settings.
`403`	Forbidden	Your account or API key is not entitled to this endpoint.
`404`	Not Found	The requested resource does not exist — for example, a lead that can’t be found by the provided email.
`429`	Too Many Requests	You exceeded a per-operation rate or parallel-request limit. Back off and retry.
`500`	Server Error	Something failed on our side. Safe to retry with backoff; if it persists, contact support.

No data is never billed

A “not found” result — an enrichment, email, or phone lookup that returns no match — is not charged. Any credits reserved for the call are released automatically, so treat a not-found response as a normal, free outcome rather than a billing event. See Pay-as-you-go.

Handling retries

429 and 5xx responses are transient. Retry them with exponential backoff (for example 1s, 2s, 4s, 8s) instead of retrying immediately in a tight loop.

Real-time operations can legitimately take up to a minute. Set client timeouts to match the recommended timeouts before treating a slow response as a failure.

A 4xx response (other than 429) means the request itself needs to change — fix the input and resend; retrying the same request unchanged will return the same error.

API Reference

Auth

Enrich

Search

Contacts

Account

Webhooks

Error response format

Status codes

No data is never billed

Handling retries

​Error response format

​Status codes

​No data is never billed

​Handling retries

Error response format

Status codes

No data is never billed

Handling retries