Copy page

API Guides

Error Handling Guide

Proper error handling is crucial for building reliable applications. This guide covers all error scenarios you might encounter when using API Codex APIs and how to handle them effectively.

Error Response Format

All API Codex APIs return consistent error responses:

Code
{
  "error": "Error type or code",
  "message": "Human-readable error description",
  "details": "Additional context about the error",
  "timestamp": "2024-01-15T10:30:00Z"
}

HTTP Status Codes

Success Codes (2xx)

Code	Status	Description
200	OK	Request successful
201	Created	Resource created successfully
202	Accepted	Request accepted for processing
204	No Content	Request successful, no content to return

Client Error Codes (4xx)

Code	Status	Description	Common Causes
400	Bad Request	Invalid request parameters	Missing required fields, invalid data types
401	Unauthorized	Authentication failed	Invalid or missing API key
403	Forbidden	Access denied	Revoked API key, endpoint not available on your plan
404	Not Found	Resource not found	Invalid endpoint, deleted resource
405	Method Not Allowed	HTTP method not supported	Using POST on GET-only endpoint
422	Unprocessable Entity	Request validation failed	Invalid email format, domain doesn't exist
429	Too Many Requests	Rate limit or credit quota exceeded	Above your plan's requests per second, or monthly credits used up

Server Error Codes (5xx)

Code	Status	Description	Action Required
500	Internal Server Error	Server-side error	Retry with exponential backoff
502	Bad Gateway	Invalid upstream response	Retry after brief delay
503	Service Unavailable	Service temporarily down	Check status page, retry later
504	Gateway Timeout	Request timeout	Retry with smaller payload

Common Error Scenarios

Authentication Errors

Invalid API Key

Code
{
  "error": "INVALID_API_KEY",
  "message": "The provided API key is invalid",
  "statusCode": 401
}

Solution: Verify your API key is correct (no extra spaces), and check that the key is still active in the dashboard. Keys are sent as an apikey query parameter or an X-Api-Key header.

Credit Quota Reached

Code
{
  "error": "QUOTA_EXCEEDED",
  "message": "Monthly credit quota reached",
  "statusCode": 429
}

Solution: Check your remaining credits in the dashboard and upgrade your plan at dash.apicodex.io/billing, or wait for the monthly reset. Consider falling back to cached data while the quota is exhausted.

Validation Errors

Missing Required Parameters

Code
{
  "error": "MISSING_PARAMETER",
  "message": "Required parameter 'domain' is missing",
  "statusCode": 400
}

Solution: Always validate required parameters before making API calls. Check the API documentation for required fields.

Invalid Data Format

Code
{
  "error": "INVALID_FORMAT",
  "message": "Invalid email format: 'not-an-email'",
  "statusCode": 422
}

Solution: Validate data format before making API calls:

• Email: Use regex ^[^\s@]+@[^\s@]+\.[^\s@]+$
• Domain: Ensure it's a valid domain format
• IP Address: Validate IPv4 or IPv6 format

Rate Limiting Errors

See our comprehensive Rate Limiting Guide for detailed handling strategies.

Implementing Error Handling

A robust error handler should:

1. Retry on transient errors (5xx, 429) with exponential backoff
2. Fail fast on client errors (4xx except 429)
3. Log all errors for debugging and monitoring
4. Parse error responses to provide meaningful messages

Code
async function makeRequestWithRetry(requestFn, maxRetries = 3) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    try {
      const response = await requestFn();
      if (response.ok) return response;

      // Retry on 5xx or 429
      if (response.status >= 500 || response.status === 429) {
        await sleep(1000 * Math.pow(2, attempt)); // Exponential backoff
        continue;
      }
      throw new Error(`API Error: ${response.status}`);
    } catch (error) {
      if (attempt === maxRetries - 1) throw error;
    }
  }
}

Error Recovery Strategies

1. Graceful Degradation

When an API call fails, fall back gracefully:

1. Return cached data if available
2. Return default/fallback data for non-critical features
3. Show user-friendly error instead of crashing

2. Circuit Breaker Pattern

Prevent cascading failures by "opening the circuit" after repeated failures:

• CLOSED: Normal operation, requests pass through
• OPEN: Too many failures, reject requests immediately for a timeout period
• HALF-OPEN: After timeout, allow one test request to determine recovery

3. Retry with Jitter

Add randomness to retry delays to prevent thundering herd:

Code
const delay = baseDelay * Math.pow(2, attempt); // Exponential backoff
const jitter = delay * 0.3 * (Math.random() * 2 - 1); // ±30% jitter
await sleep(delay + jitter);

Error Monitoring

For production applications, integrate with error monitoring services:

• Sentry - Real-time error tracking
• LogRocket - Session replay with errors
• DataDog - APM and error monitoring
• Custom webhooks - Send errors to Slack, PagerDuty, etc.

Track metrics like:

• Total errors by status code
• Error rate over time
• Most frequent error types
• Time to detection and resolution

Best Practices

Do's ✅

1. Always validate input before making API calls
2. Implement retry logic with exponential backoff
3. Log all errors for debugging and monitoring
4. Use circuit breakers to prevent cascade failures
5. Provide meaningful error messages to users
6. Cache successful responses for fallback
7. Monitor error rates and set up alerts

Don'ts ❌

1. Don't ignore errors - Always handle them
2. Don't retry infinitely - Set reasonable limits
3. Don't expose sensitive information in error messages
4. Don't retry non-retryable errors (4xx except 429)
5. Don't break on non-critical errors - Degrade gracefully

Next Steps

• Review Rate Limiting for handling 429 errors
• Learn Authentication best practices
• Explore Best Practices for production
• Browse our API Catalog to start building