Error Handling

​

Overview

​

Error Response Format

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
  "details": "Human-readable error description",
  "correlation_id": "unique-id-for-troubleshooting",
}

​

HTTP Status Codes

​

Error Types

​

Authentication Errors (401)

​

Credit Errors (403)

​

Validation Errors (422)

HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json

{
  "detail": [
    {
      "loc": ["body", "field_name"],
      "msg": "validation error message",
      "type": "error_type",
      "ctx": { "additional": "context" }
    }
  ]
}

​

Client Errors (400)

​

Server Errors (500)

​

Rate Limiting

{
  "code": 429,
  "message": "Rate limit exceeded. Please retry after the specified time.",
  "retry_after": 60  // Seconds to wait before retrying
}

• X-RateLimit-Limit: Maximum requests per window
• X-RateLimit-Remaining: Requests remaining in current window
• X-RateLimit-Reset: Unix timestamp when limit resets

​

Best Practices

​

DO

• Log correlation IDs for all errors to facilitate debugging
• Implement retry logic with exponential backoff for 5xx errors
• Monitor credit usage to avoid unexpected 403 errors
• Validate requests client-side to minimize 422 errors
• Handle rate limits gracefully using the retry_after value

​

DON’T

• Don’t retry 4xx errors without fixing the root cause
• Don’t ignore correlation IDs when reporting issues
• Don’t make parallel requests that might exceed rate limits
• Don’t cache error responses

​

Error Handling Examples

import requests
from time import sleep

def make_api_request(url, headers, data):
    response = requests.post(url, headers=headers, json=data)

    if response.status_code == 429:
        retry_after = int(response.headers.get('Retry-After', 60))
        sleep(retry_after)
        return make_api_request(url, headers, data)

    if response.status_code >= 500:
        # Implement exponential backoff
        for attempt in range(3):
            sleep(2 ** attempt)
            response = requests.post(url, headers=headers, json=data)
            if response.status_code < 500:
                break

    if response.status_code >= 400:
        error_data = response.json()
        print(f"Error: {error_data['message']}")
        print(f"Correlation ID: {error_data['correlation_id']}")

    return response

async function makeApiRequest(url, headers, data) {
  const response = await fetch(url, {
    method: 'POST',
    headers: headers,
    body: JSON.stringify(data)
  });

  if (response.status === 429) {
    const retryAfter = parseInt(response.headers.get('Retry-After') || '60');
    await new Promise(resolve => setTimeout(resolve, retryAfter * 1000));
    return makeApiRequest(url, headers, data);
  }

  if (!response.ok) {
    const error = await response.json();
    console.error(\`Error: ${error.message}\`);
    console.error(\`Correlation ID: ${error.correlation_id}\`);
    throw new Error(error.message);
  }

  return response.json();
}

​

Troubleshooting

​

Quick Troubleshooting Tips

• 401 Errors: Double-check your Partner ID and API key
• 403 Errors: Verify your credit balance in the dashboard
• 422 Errors: Review the validation error details and adjust your request
• 429 Errors: Implement rate limiting in your application
• 500 Errors: These are usually temporary - retry with exponential backoff

​

Change Log