Errors and recovery
Introduction
Capability calls, estimates, submissions and result queries have no platform per-minute request quota or per-account task-count quota. Stored files have no account-wide count or total-byte quota. Actual data source capacity, per-file and protocol validation, authorization and credits still apply. A source may return 429 with a concrete failure reason.
The HTTP status indicates request failure, error.code is machine-readable, and error.message carries the safe concrete reason when known. Preserve the response header X-Request-ID to identify an entry rejection even when no task was created. Native protocol endpoints retain their compatible error envelope. Handle the specific code; do not retry every error the same way. Social validation errors identify the first failing field (for example error.field=input.note_id) and explain its expected type, format or conflicting fields in error.message; input values are omitted. Validation failures (400 invalid_input) also carry error.message explaining what to correct and, when one can be identified, error.field naming the offending field or header; nothing is submitted or charged when that status is returned.
{"error":{"code":"invalid_input","field":"input.note_id","message":"input.note_id must be a 24-character hexadecimal note ID","request_id":"example-request-id","outcome":"not_submitted","retry_action":"correct_input"}}| Status | Meaning | Typical codes |
|---|---|---|
| 400 | Invalid parameters or material. | invalid_input |
| 401 | Missing or invalid key. | unauthorized |
| 402 | Insufficient credits. | insufficient_credits |
| 403 | Not permitted for this source or account. | forbidden |
| 404 | Unknown source or task not owned. | not_found |
| 409 | Quote, request or idempotency conflict. | conflict |
| 429 | Data source capacity or upstream throttling. | concurrency_limit_reached |
| 503 | Configuration or service temporarily unavailable. | — |
- A timeout, a dropped connection or a 5xx response does not prove failure.
- Read the task with the UUID you already saved; a 404 does not prove the provider never received it.
- GET requests may retry with bounded backoff; leave
pendingtasks for reconciliation.