Documentation

Error Codes Reference

Comprehensive reference for API error codes and how to handle them

Error Response Format

Most API errors return a JSON body with an error code, message, and optional details for debugging. The exact shape depends on which layer raised the error — see below.

Error Body Shapes

Errors raised by middleware (for example, rate limiting) use the richer envelope with a structured error object and a request_id:

json

{
  "error": {
    "code": "RATE_LIMIT_ERROR",
    "message": "Rate limit exceeded: 100 calls per 60 seconds",
    "details": {}
  },
  "request_id": "550e8400-e29b-41d4-a716-446655440000"
}

Errors raised by the framework via HTTPException (validation failures, permission errors, 404s, most business-rule errors) use FastAPI's default { "detail": ... } shape. detail may be a string or an object depending on the endpoint:

json

{
  "detail": "Rule not found"
}

// or, for structured errors:
{
  "detail": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid request parameters",
    "field": "limit"
  }
}

When a request_id is present, always include it when contacting support for faster debugging.

HTTP Status Codes

200OK

Request succeeded

201Created

Resource created successfully

204No Content

Request succeeded, no content to return (typically for DELETE)

400Bad Request

Invalid request syntax or parameters

401Unauthorized

Missing or invalid API key

403Forbidden

Valid API key but insufficient permissions or scope

404Not Found

Resource does not exist or you don't have access

409Conflict

Resource already exists (e.g., duplicate upload)

402Payment Required

Subscription is past due or payment required

422Unprocessable Entity

Request is well-formed but contains validation errors or violates business rules

429Too Many Requests

Rate limit exceeded. Check Retry-After header.

500Internal Server Error

Server error. Retry with exponential backoff.

503Service Unavailable

AI provider error, upstream service failure, or temporary overload. Retry after a short delay.

504Gateway Timeout

Operation timed out. Retry with a smaller batch size or simpler query.

Application Error Codes

The codes below are the most common ones you will encounter. Individual endpoints may emit additional endpoint-specific codes (for example, custom extraction schemas, cloud storage, and billing flows each define their own set) — consult the relevant endpoint reference for the full list.

Authentication Errors

INVALID_API_KEY

The API key provided is invalid or malformed

Solution: Check that you're using a valid API key from your dashboard

EXPIRED_API_KEY

The API key has expired

Solution: Generate a new API key from your dashboard

DEACTIVATED_API_KEY

The API key has been deactivated

Solution: Generate a new API key from your dashboard

AUTHZ_ERROR

API key lacks required authorization for this operation

Solution: Create a new API key with the required scope

Upload Errors

HTTP_413

File exceeds maximum size limit or storage quota exceeded

Solution: Reduce file size. Check the message for details.

Quota Errors

STORAGE_QUOTA_EXCEEDED

Account storage limit reached

Solution: Delete unused files or upgrade your plan

RATE_LIMIT_ERROR

Too many API requests in the time window

Solution: Implement exponential backoff and respect Retry-After

USAGE_LIMIT_EXCEEDED

Monthly API call or processing limit reached

Solution: Wait for next billing cycle or upgrade plan

Processing Errors

IMAGE_PROCESSING_ERROR

Image processing or analysis failed

Solution: Check file integrity and try re-uploading

VLM_PROVIDER_ERROR

AI vision provider encountered an error during analysis

Solution: Retry the request. If the error persists, the provider may be temporarily unavailable.

TIMEOUT

Operation timed out

Solution: Retry with smaller batch size or simpler query

Error Handling Best Practices

python

import requests
import time
import random

def api_request_with_retry(method, url, max_retries=3, **kwargs):
    """Make API request with exponential backoff."""
    for attempt in range(max_retries):
        response = requests.request(method, url, **kwargs)

        if response.status_code == 200:
            return response.json()

        if response.status_code == 429:
            # Rate limited - use Retry-After header
            retry_after = int(response.headers.get('Retry-After', 5))
            print(f"Rate limited. Waiting {retry_after}s...")
            time.sleep(retry_after)
            continue

        if response.status_code >= 500:
            # Server error - exponential backoff
            wait_time = (2 ** attempt) + (random.random() * 0.5)
            print(f"Server error. Retrying in {wait_time:.1f}s...")
            time.sleep(wait_time)
            continue

        # Client error - don't retry
        data = response.json()
        error = data.get('error', {})
        raise APIError(
            code=error.get('code'),
            message=error.get('message'),
            request_id=data.get('request_id')
        )

    raise MaxRetriesExceeded(f"Failed after {max_retries} attempts")

Rate Limits

Understand rate limiting and best practices

Authentication

API key setup and management