Errors & rate limits

The error envelope

Every non-2xx response has one error object:

{
  "error": {
    "code": "insufficient_available_credits",
    "message": "Available credits are below the confirmed estimate.",
    "required": {"units": 400, "unit_scale": 1000},
    "shortfall": {"units": 125, "unit_scale": 1000}
  }
}

Branch on code. It is stable and machine-readable. Never match on message: human-facing copy may change without notice.

Some errors add typed context such as the current wallet, replacement quote or effective limit. Raw provider responses, secrets and callback URLs are never returned in error context.

Codes

Status	`code`	Meaning	Fix
`400`	`invalid_input`	The input could not be parsed into a company.	Send a LinkedIn company URL, slug, or numeric id.
`400`	`unsupported_operation`	Unknown operation.	Use `target_people`.
`400`	`persona_required`	No persona slug was submitted.	Pass an existing persona slug.
`400`	`persona_not_found`	The persona is not in your account.	List or create it with `/v1/personas`.
`400`	`invalid_idempotency_key`	The required key is empty or over 128 characters.	Send a stable 1–128 character key.
`400`	`cursor_invalid`	The cursor is malformed or belongs to another account/query.	Restart pagination from the first page.
`409`	`idempotency_conflict`	The key was used for a different request.	Reuse the original payload or choose a new key.
`409`	`revision_conflict`	The draft changed in another tab or client.	Read and review its current revision.
`409`	`quote_changed`	Revalidation increased the estimate; no hold was created.	Show and confirm the replacement quote.
`409`	`quote_not_ready`	The draft has no confirmable quote.	Poll or handle its typed terminal state.
`409`	`draft_expired`	The estimate exceeded its fixed lifetime.	Create a new estimate.
`409`	`system_persona_immutable`	An edit/delete targeted Owners & founders.	Choose a custom persona.
`401`	`missing_api_key`	No API key.	Add `X-API-Key`.
`401`	`invalid_api_key`	The key is unknown or inactive.	Check the key in the dashboard.
`402`	`insufficient_available_credits`	Concurrent holds leave less Available than the quote.	Review the wallet/shortfall or wait for a release.
`403`	`commercial_access_not_enabled`	This metered account may estimate but is not enabled to execute paid searches.	Contact the account owner; do not retry confirmation automatically.
`404`	`draft_not_found`	No such draft under your key.	Check the draft ID and account.
`404`	`job_not_found`	No such confirmed job under your key.	Check the job ID and account.
`422`	`validation_error`	Body or parameters failed validation.	Fix the fields in `details`.
`429`	`draft_limit`	Too many resumable estimates.	Confirm or discard an existing draft.
`429`	`concurrency_limit`	Too many executable jobs are active.	Wait for or cancel one.

Handling confirmation errors

Python

r = requests.post(confirm_url, headers=headers, json=reviewed_quote)
if not r.ok:
    err = r.json()["error"]
    if err["code"] == "quote_changed":
        show_replacement(err)            # no reservation was created
    elif err["code"] == "insufficient_available_credits":
        show_shortfall(err)
    elif err["code"] == "concurrency_limit":
        wait_and_retry_same_key()
    else:
        raise RuntimeError(err["message"])

Concurrency and bounded reads

Reads are bounded and cursor-paginated. Resumable drafts and executable jobs have separate controls returned by GET /v1/account; a free estimate does not bypass the active-draft cap. Over executable concurrency, confirmation returns:

{"error":{"code":"concurrency_limit","message":"Wait for an active search to finish.","limit":1}}

Re-polling a finished job and replaying the same Idempotency-Key are safe, so a lost response never requires duplicate confirmation.

Terminal job states

not_found, no_employees, no_people_found, too_large, failed, and cancelled are terminal statuses, not necessarily HTTP errors. Their billing object shows the exact captured and released components; do not infer money from status text.

Get started

Guides

Billing & errors

Errors & rate limits

The error envelope

Codes

Handling confirmation errors

Concurrency and bounded reads

Terminal job states

​The error envelope

​Codes

​Handling confirmation errors

​Concurrency and bounded reads

​Terminal job states

The error envelope

Codes

Handling confirmation errors

Concurrency and bounded reads

Terminal job states