Documentation

Error Handling

Learn how to handle errors gracefully in your integration.

Error Response Format

All errors follow a consistent format:

json
{
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable error message"
  }
}

Common Error Codes

Authentication Errors (401)

CodeDescriptionSolution
AUTHENTICATION_FAILEDAuthentication failedCheck your API key format
INVALID_API_KEYThe provided API key is invalidGenerate a new API key
EXPIRED_API_KEYThe API key has expiredGenerate a new API key
REVOKED_API_KEYThe API key has been revokedGenerate a new API key

Authorization Errors (403)

CodeDescriptionSolution
AUTHORIZATION_FAILEDYou do not have permission to access this resourceCheck your API key permissions
SUSPENDED_ACCOUNTThe client account has been suspendedContact support
INSUFFICIENT_PERMISSIONSThe API key does not have the required permissionsUse an API key with appropriate permissions

Request Errors (400)

CodeDescriptionSolution
INVALID_REQUESTThe request is malformed or contains invalid parametersCheck request body format
MISSING_PARAMETERA required parameter is missingInclude all required fields
INVALID_PARAMETERA parameter has an invalid valueVerify parameter values
INVALID_FORMATThe request format is invalidCheck Content-Type and JSON syntax
INSUFFICIENT_BALANCEAccount balance is below the minimum requiredAdd funds to your account

Not Found Errors (404)

CodeDescriptionSolution
RESOURCE_NOT_FOUNDThe requested resource was not foundVerify the resource ID
JOB_NOT_FOUNDThe specified job was not foundCheck the job ID
CLIENT_NOT_FOUNDThe specified client was not foundVerify client ID
API_KEY_NOT_FOUNDThe specified API key was not foundCheck the key ID

Rate Limiting (429)

CodeDescriptionSolution
RATE_LIMIT_EXCEEDEDRate limit exceededWait and retry with exponential backoff

Server Errors (500)

CodeDescriptionSolution
INTERNAL_ERRORAn internal server error occurredRetry with exponential backoff
PROCESSING_FAILEDJob processing failedCheck job details for error information
DATABASE_ERRORA database error occurredRetry after a delay
EXTERNAL_SERVICE_ERRORAn external service error occurredRetry after a delay

Service Unavailable (503)

CodeDescriptionSolution
SERVICE_UNAVAILABLEThe service is temporarily unavailableRetry after a delay

Retry Strategy

Implement exponential backoff for transient errors:

Python

python
import time
import requests

def make_request_with_retry(url, headers, data, max_retries=3):
    for attempt in range(max_retries):
        try:
            response = requests.post(url, json=data, headers=headers)
            
            if response.status_code == 200:
                return response.json()
            elif response.status_code in [429, 500, 503]:
                # Retry with exponential backoff
                wait_time = 2 ** attempt
                time.sleep(wait_time)
            else:
                # Don't retry client errors
                response.raise_for_status()
        except requests.exceptions.RequestException as e:
            if attempt == max_retries - 1:
                raise
            time.sleep(2 ** attempt)
    
    raise Exception("Max retries exceeded")

JavaScript

javascript
async function makeRequestWithRetry(url, options, maxRetries = 3) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    try {
      const response = await fetch(url, options);
      
      if (response.ok) {
        return await response.json();
      }
      
      if ([429, 500, 503].includes(response.status)) {
        // Retry with exponential backoff
        const waitTime = Math.pow(2, attempt) * 1000;
        await new Promise(resolve => setTimeout(resolve, waitTime));
      } else {
        // Don't retry client errors
        throw new Error(`HTTP ${response.status}: ${await response.text()}`);
      }
    } catch (error) {
      if (attempt === maxRetries - 1) {
        throw error;
      }
      const waitTime = Math.pow(2, attempt) * 1000;
      await new Promise(resolve => setTimeout(resolve, waitTime));
    }
  }
  
  throw new Error('Max retries exceeded');
}

Best Practices

  1. Always check HTTP status codes before parsing response
  2. Implement retry logic for 429, 500, and 503 errors
  3. Log errors with context for debugging
  4. Handle rate limits gracefully with exponential backoff
  5. Validate inputs before making API calls
  6. Monitor error rates to detect issues early