Error Handling

Documentation Index

Fetch the complete documentation index at: https://developers.explorium.ai/llms.txt

Use this file to discover all available pages before exploring further.

​

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

​

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