Skip to main content
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

CodeMeaningWhen it happens
400Bad RequestMissing or invalid parameters, an unsupported filter for the chosen mode, a malformed LinkedIn URL, or a lookup that matched no record.
401UnauthorizedMissing Authorization header or an invalid token. See Authentication.
402Payment RequiredNot enough balance to run the operation ("Insufficient funds in the account."). Top up in your billing settings.
403ForbiddenYour account or API key is not entitled to this endpoint.
404Not FoundThe requested resource does not exist — for example, a lead that can’t be found by the provided email.
429Too Many RequestsYou exceeded a per-operation rate or parallel-request limit. Back off and retry.
500Server ErrorSomething 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.