Documentation

Error Codes Reference

Comprehensive reference for API error codes and how to handle them

Error Response Format

All API errors follow a consistent JSON format with an error code, message, and optional details for debugging.

Standard Error Format

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid request parameters",
    "details": {
      "field": "limit",
      "issue": "Must be between 1 and 100"
    }
  },
  "request_id": "550e8400-e29b-41d4-a716-446655440000"
}

Always include the request_id 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 or upstream service failure

503Service Unavailable

Temporary overload. Retry after a short delay.

Application Error Codes

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 or use chunked upload for videos. Check the message for details.

CHUNK_UPLOAD_ERROR

Video chunk upload failed (invalid chunk number, size, or parameters)

Solution: Verify chunk boundaries and retry using the retry endpoint

MEMORY_LIMIT_EXCEEDED

Server is temporarily overloaded with concurrent uploads

Solution: Wait for current uploads to complete before starting new ones. Check Retry-After header.

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

CONCURRENT_UPLOAD_LIMIT_EXCEEDED

Maximum concurrent operations reached

Solution: Wait for current operations to complete

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

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