Errors

Many route-level business failures use a stable envelope:

{
  "success": false,
  "error": {
    "code": "FEATURE_NOT_AVAILABLE",
    "message": "Feature unavailable on current plan",
    "details": {}
  }
}

Common error codes

• INVALID_REQUEST – malformed payload or validation error
• UNAUTHORIZED – missing/invalid credentials
• INVALID_KEY / INVALID_API_KEY / KEY_NOT_FOUND – key does not exist, malformed, or revoked
• FORBIDDEN – authenticated user lacks permission for this route
• RATE_LIMIT_EXCEEDED – too many requests in current window
• QUOTA_EXCEEDED – daily/plan quota is exhausted
• FEATURE_NOT_AVAILABLE – feature blocked for plan
• JOB_NOT_FOUND – unknown job id
• JOB_NOT_COMPLETED – result not ready yet
• JOB_FAILED – job failed after processing
• BATCH_NOT_FOUND – unknown batch id
• LIMITS_ERROR – internal usage/limit accounting failure
• LIST_ERROR – list/filter retrieval failure
• RESULTS_ERROR – unable to assemble result payload

HTTP status mapping

Do not assume every failure maps cleanly to an HTTP status. The current backend mixes two patterns:

• application/business-rule failures often return success: false via the JSON envelope
• auth, CSRF/origin, and throttling failures are commonly raised as real HTTP errors
• 400/422: request/validation errors
• 401: missing or invalid auth credentials
• 403: permission denied, invalid origin, CSRF failure, or runtime-disabled feature
• 404: missing job/batch/resource on routes that raise HTTPException
• 429: throttled API-key request
• 500: unexpected internal failure

Examples of envelope-style failures that may still arrive with HTTP 200 today:

• FEATURE_NOT_AVAILABLE
• QUOTA_EXCEEDED
• JOB_NOT_FOUND
• JOB_NOT_COMPLETED