unauthenticated | 401 | false | Authentication is missing or invalid. | Supply a valid API key or refresh your access token. |
insufficient_credits | 402 | false | Billing or credit limits prevent this request. | Check your subscription, balance and team spending limits before retrying. |
validation_error | 422 | false | Request parameters failed validation. | Correct the parameters named in param and detail. |
rate_limited | 429 | true | A request or concurrency limit was reached. | Follow Retry-After and reduce request concurrency. |
not_found | 404 | false | The resource does not exist or is not visible to this caller. | Check the ID and your organization and team context. |
forbidden | 403 | false | This caller lacks permission for the action. | Check permissions and organization or team membership. |
idempotency_key_reused | 409 | false | The key was already used with a different request. | Keep the original body for a retry; use a new key for different work. |
invalid_cursor | 400 | false | The cursor is invalid or does not match this request. | Restart pagination without a cursor. Keep the source, filters and page size unchanged between pages. |
limit_exceeded | 422 | false | The request exceeds a supported limit. | Reduce the requested size or wait for capacity, as detail directs. |
job_not_finished | 409 | true | This action requires a finished Job. | Poll until the Job succeeds, fails or is canceled, then try again. |
items_not_available | 409 | false | Per-record items are unavailable or cannot be safely matched to their inputs. | If the Job is running, wait for it to finish. Otherwise check result for files or contact support; do not restart paid research automatically. |
request_in_progress | 409 | true | A matching start request is still being registered. | Follow Retry-After, then repeat the unchanged request with the same key. |
list_not_ready | 409 | true | The list is not ready for this action. | Wait for ready. If list creation failed, correct its source before creating a replacement. |
unsupported_file | 422 | false | The file format is unsupported. | Use a format accepted by the Files API. |
invalid_upload | 422 | false | The contents, declared size or upload ticket failed validation. | Check the file and its size; request a fresh upload ticket if needed. |
file_too_large | 413 | false | The file exceeds the applicable byte limit. | Split or reduce the file. Check the limit for the upload method you use. |
entity_type_mismatch | 422 | false | The source has a different people or company type. | Use a source matching the entity type requested by this action. |
export_source_changed | 409 | false | The export source changed since your first request. | Start a new export with a new key after the source is stable. |
job_execution_changed | 409 | false | The Job changed execution while it was being read. | Read the Job again and restart item pagination without a cursor. |
item_failed | 422 | false | One input record could not be processed. | Inspect the item’s error.detail; deliberately retry only affected records with a new key. |
job_failed | 500 | false | The Job ended with an execution error. | Inspect its error and available successful items before starting replacement work. |
unavailable | 503 | true | The service is temporarily unavailable. | Follow Retry-After and retry unchanged. Keep the same key on a start request. |
internal_error | 500 | true | The service encountered an unexpected error. | Follow Retry-After; keep the same start key. Contact support with the request ID if it persists. |
timed_out | 504 | false | Execution reached a timeout. | Inspect the Job and saved results before starting replacement work. Expiring wait_seconds alone returns 202, not this error. |
aborted | 409 | false | The Job was terminated before completion. | Inspect its status and available results before starting replacement work. |