For the complete documentation index, see llms.txt. This page is also available as Markdown.
Errors and retries
Every error returns the same envelope. Branch on error.code, never on message — messages change,
codes are part of the compatibility contract.
json
{ "error": { "type": "invalid_request_error", "code": "parameter_missing",
"message": "Missing required parameter: query.", "param": "query",
"doc_url": "https://docs.scispace.com/api-reference/searches",
"request_id": "req_2f9a7c41d0" } }Error types
error.type is an exhaustive enum.
| HTTP | type | Retry? | Meaning |
|---|---|---|---|
| 400 | invalid_request_error | no | Malformed, missing, or out-of-range parameters |
| 401 | authentication_error | no | Missing, malformed, or revoked key |
| 402 | insufficient_credits_error | no | Balance or per-key cap exhausted |
| 403 | permission_error | no | Key lacks the required scope, or content is not licensed to you |
| 404 | not_found_error | no | Unknown, expired, or deleted resource |
| 409 | conflict_error | no | Resource is in the wrong state for this call |
| 413 | payload_too_large_error | no | Input or source count over the cap |
| 422 | unprocessable_error | no | Well-formed but unusable — unparseable PDF, unsupported language |
| 429 | rate_limit_error | yes, after Retry-After | Too many requests |
| 500 | api_error | yes, with backoff | Our fault |
| 503 | service_unavailable_error | yes, with backoff | Temporary capacity |
Common codes
code | Type | Where |
|---|---|---|
parameter_missing, parameter_invalid, parameter_unknown | 400 | everywhere |
query_too_long | 400 | searches — 1,000 character cap |
no_sources | 400 | chats, extractions |
schema_invalid | 400 | extractions |
csl_invalid | 400 | citations |
unsupported_file_type, file_too_large | 400 | files |
insufficient_credits | 402 | any metered call |
scope_missing | 403 | any |
full_text_not_licensed | 403 | papers |
paper_not_found, resource_expired | 404 | papers, async resources after 90 days |
document_not_ready | 409 | chats, extractions |
search_not_cancelable | 409 | searches |
too_many_sources | 413 | chats (50), extractions (500) |
text_too_long | 413 | paraphrases (5,000 words), ai-detections (15,000 words) |
document_unparseable | 422 | documents |
language_unsupported | 422 | any language parameter — see chats |
rate_limit_exceeded | 429 | any |
Retry strategy
Retry only 429, 500, and 503.
Text
attempt 1 → wait 1s ± jitter
attempt 2 → wait 2s ± jitter
attempt 3 → wait 4s ± jitter
attempt 4 → wait 8s ± jitter
attempt 5 → give up, surface the request_idOn 429, honour Retry-After instead of your own schedule. Always send Idempotency-Key so a retry
cannot be charged twice — a replay within 24 hours returns the original response.
Failed jobs are not transport errors
An async resource that reaches status: "failed" returns 200 with an error object on the resource.
Read it and fix the input; retrying an identical failed job costs credits and fails again.
Getting help
Every response carries X-Request-Id. Quote it — see get-support.
Related
Last updated