Errors

HTTP errors use a JSON envelope:

{
  "object": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "limit must be between 1 and 500",
    "param": "limit",
    "request_id": "req_..."
  }
}

param and request_id are omitted when unavailable. A request ID can also appear in the X-Request-Id response header.

HTTP status codes

Status	Error type	Meaning
`401`	`authentication_error`	The API key is missing, malformed, or unknown.
`402`	`insufficient_credits`	The account cannot reserve the maximum request cost.
`403`	`authentication_error`	The key is revoked, expired, or lacks endpoint access.
`404`	`not_found`	An Entity Search task does not exist or belongs to another API key.
`409`	`idempotency_error`	The same idempotency key was reused with different input.
`409`	`request_in_progress`	Entity task creation has not produced a stable task handle yet.
`409`	`request_expired`	The Entity Search replay window expired and the old task is no longer accessible.
`409`	`request_already_exists`	A synchronous paid request with this key exists but has no completed response to replay.
`422`	`invalid_request_error`	A header, JSON body, query parameter, field value, or request size is invalid.
`429`	`concurrency_limit`	The user-level or global concurrency limit was reached.
`500`	`internal_error`	An internal dependency, upstream operation, protocol check, or settlement failed.
`503`	`service_unavailable`	The endpoint or requested type is not enabled or priced.

The API redacts upstream response bodies and implementation details. A failed Entity Search status contains only status.error: "internal error"; already prepared results can still be fetched. Not every status applies to every endpoint. Credit balance does not reserve credits and therefore does not return search billing, task, or idempotency errors. Entity Search also returns 422 invalid_request_error when entity_type is xiaohongshu or wechat and enable_web_search is omitted or set to false. The wechat entity type searches WeChat Official Accounts.

Task-level failures

An Entity Search task can fail after create_task succeeds. In that case, Status returns HTTP 200 with the failure nested under status:

{
  "object": "entity_search_status",
  "leads_search_id": "leads_search_01JABCDEF123456789",
  "status": {
    "status": "error",
    "verified_count": 12,
    "ready_count": 5,
    "error": "internal error"
  }
}

The task failed, but its five ready results remain available through Fetch.

Retry guidance

Condition	Guidance
`401`, `402`, `403`, `404`, `422`	Fix the credential, balance, task ID, or request before retrying.
`429`	Wait before creating another task or synchronous paid request. The API does not currently return `Retry-After`.
Lost Entity Search create response	If you supplied a stable `Idempotency-Key`, retry the same body with that key; do not create a new logical task.
`409 request_in_progress`	Preserve the original key and request ID. Wait before retrying the same create request.
`409 request_expired`	Treat the old task as closed. Start a new logical search only when you intentionally accept a new charge.
Entity Status or Fetch `500`	Retry that read with backoff. Keep the original `leads_search_id`.
Lost Contact Search response	Retry the same body with the same known key. A completed response is replayed without another search call or charge.
Lost Deep Search, Enrich, or Extract response	Retry the same body with the same known key. A completed response is replayed without another upstream call or charge.
`500` during a paid POST	Do not switch to a new key automatically; the original request may still require recovery.

Log the HTTP status, error type, request_id, X-Request-Id, and leads_search_id. Never log the API key or sensitive objective and result data.

Getting started

API reference

MCP

API behavior

HTTP status codes

Task-level failures

Retry guidance

​HTTP status codes

​Task-level failures

​Retry guidance

HTTP status codes

Task-level failures

Retry guidance