Errors
Every error type, its status code, and whether it is billed.
#Error shape
Every error, on every endpoint, has the same envelope:
{
"error": {
"type": "unprocessable_target",
"message": "This profile is private or has been deleted.",
"requestId": "req_9k2mm4xd"
}
}requestId rides along on every response, success or failure - include it when you contact support.
#Error types
| Status | Type | When | Billed |
|---|---|---|---|
| 400 | invalid_request |
Malformed body, unknown field, or a bad URL format | No |
| 401 | invalid_api_key |
Missing, malformed, or revoked key | No |
| 402 | insufficient_credits |
The key is valid, but your balance cannot cover the call | No |
| 404 | not_found |
The batch job referenced by job_id does not exist |
No |
| 422 | unprocessable_target |
The target profile, company, or post is not found, private, deleted, or unreachable | Yes - everywhere, including profiles/activity and each batch item |
| 429 | rate_limited |
Over the request, search, or concurrent-batch limit; honor Retry-After |
No |
| 500 | internal_error |
Something broke on our side | No |
| 504 | upstream_timeout |
The live scrape did not finish in time | No |
| n/a | upstream_error |
Another upstream scrape failure, distinct from a timeout | No |
upstream_error covers an upstream scrape failure other than a timeout. It's never billed, and safe to retry the same as upstream_timeout.
#Retries
429, 500, and 504 (and upstream_error) are safe to retry - outside a batch job, none of them are billed. Use exponential backoff with jitter, and treat Retry-After as a floor, not a fixed delay.
POST /v1/batch accepts an Idempotency-Key header so a retried submission returns the original job instead of creating a duplicate - see Batch jobs.
#Batch items fail individually
A batch job never fails as a whole because one item did. Each entry in results or failures carries its own status and its own operation. A profile, company, post, or Sales Navigator search item was already billed in full at submission: a success, an unprocessable_target failure, and a 500 or 504 failure all bill the same - 1 credit per enrich item, or a max_results-sized reservation per Sales Navigator search item - and the only refund is the unused part of that reservation, once the search runs. Every other operation item reserves the same worst case at submission but settles once its queue finishes: a failed item (unprocessable_target, or a company or job that isn't found) costs 0 and refunds in full, the same as an empty result. Items still processing affect neither count. See Credits for the full rate table and Rate limits for the quota headers.