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.

JSON
{"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"}}
StatusMeaningTypical codes
400Invalid parameters or material.invalid_input
401Missing or invalid key.unauthorized
402Insufficient credits.insufficient_credits
403Not permitted for this source or account.forbidden
404Unknown source or task not owned.not_found
409Quote, request or idempotency conflict.conflict
429Data source capacity or upstream throttling.concurrency_limit_reached
503Configuration 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 pending tasks for reconciliation.
Never blind-resubmit a billable generation with a new idempotency key after an ambiguous outcome.