Getting started

Errors

Error envelope, status codes, and retry guidance.

Errors return JSON with a detail message; some carry an additional machine code:

{
  "detail": "rate limited",
  "code": "rate_limited"
}

Validation failures (422) use a structured detail array instead, with the offending location and message per field:

{
  "detail": [
    {
      "loc": ["body", "items"],
      "msg": "Field required",
      "type": "missing"
    }
  ]
}

Status codes

StatusMeaningRetry?
400Malformed request.No. Fix the request.
401Missing or invalid API key.No. Check the key.
402Monthly quota exhausted.No. Upgrade, or wait for the cycle reset.
403Authenticated but not permitted.No.
404Not found, including namespaces outside your key's scope.No.
405Wrong HTTP method for the path.No.
409Conflict, such as retrying an operation that is not dead-lettered.No. Check state first.
410Resource gone.No.
413Upload too large.No. Reduce the file size.
422Body failed validation.No. Fix the fields in detail.
429Rate limited.Yes. Honor Retry-After.
503Overloaded; request shed.Yes. Retry with backoff.

Retry guidance

Only 429 and 503 are retryable, and both include a Retry-After header. Use exponential backoff with jitter and cap total attempts. Commit is idempotent per content batch: a duplicate in-flight commit collapses onto the existing operation, so retrying a timed-out commit is safe.

Asynchronous failures

Commit processes asynchronously. A 200 from commit means the work was accepted; extraction failures surface on the operations API. A commit that exhausts its retries dead-letters: list failed work with state=failed, read the terminal error on the status route, and re-run it with the retry endpoint.

Search docs

Search the documentation