Errors and status codes

​

Common status codes

• 200 OK: synchronous read success
• 202 Accepted: async job accepted
• 400 Bad Request: request shape is valid but business constraints failed
• 401 Unauthorized: missing or invalid auth
• 402 Payment Required: insufficient credits
• 404 Not Found: job, file, or token not found
• 410 Gone: download token expired
• 422 Unprocessable Entity: validation error from request parsing
• 500 Internal Server Error: unexpected failure
• 503 Service Unavailable: required storage/service not available

​

Error body patterns

{
  "status": "error",
  "error": "Job not found",
  "job_id": "..."
}

{
  "detail": "Missing or invalid authentication. Provide X-API-Key header."
}

{
  "status": "error",
  "error": "insufficient_credits",
  "feature": "parse",
  "required": 12,
  "balance": 3
}

​

Validation errors