Error Handling

Overview

The Explorium API uses standard HTTP response codes to indicate the success or failure of requests. Responses include detailed error information to help you identify and resolve issues quickly.

Error Response Format

All error responses follow a consistent structure:

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

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

📘

Important

The correlation_id is crucial for troubleshooting. Always include it when contacting support.

HTTP Status Codes

Error Types

Authentication Errors (401)

Credit Errors (403)

Validation Errors (422)

Validation errors return a detailed structure indicating which fields failed validation:

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" }
    }
  ]
}

Common Validation Errors:

Client Errors (400)

Server Errors (500)

Rate Limiting

When you exceed API rate limits, you'll receive a 429 response:

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

Rate Limit Headers:

• 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

🚧

When Contacting Support

Please provide the following information:

1. Correlation ID from the error response
2. Request details:
   • Endpoint URL
   • HTTP method
   • Request headers (excluding sensitive data)
   • Request body
3. Timestamp of the error
4. Error message and status code

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

💬

Need Help?

Contact our support team through your dedicated Slack channel with Explorium.