Error Codes

Every API Express error returns a structured JSON response with a specific error code and human-readable message. This reference helps you handle every failure type gracefully.

Overview

API Express uses standard HTTP status codes combined with specific error codes in the response body. The HTTP status tells you the category (client error, server error). The error code tells you exactly what happened.

All errors return a consistent JSON structure — same format across all 10 APIs. This means you can write one error handler that works for every endpoint.

Error Response Format

Every error response follows this structure:

{
  "status": "error",
  "code": "INVALID_API_KEY",
  "message": "The API key provided is invalid or has been revoked.",
  "http_status": 401,
  "request_id": "req_1a2b3c4d5e6f",
  "timestamp": "2026-10-05T10:30:42Z"
}

Field descriptions

HTTP Status Codes

API Express uses the following HTTP status codes. Understanding the categories helps you build correct retry and error-handling logic.

Error Code Reference

Below is the complete list of error codes returned by API Express, grouped by HTTP status.

Authentication errors (401)

Authorization errors (403)

Validation errors (400)

Not found (404)

Business logic errors (422)

Rate limiting (429)

Server errors (5xx)

Recommended Handling

Handle errors by category, not by individual error code. This keeps your code clean and future-proof.

Node.js example

const res = await fetch(url, { headers });
const data = await res.json();

if (res.ok) {
  // Success — process data
  return data;
}

// Handle errors by HTTP status category
switch (res.status) {
  case 401:
    // Authentication problem — check API key
    console.error('Auth error:', data.code);
    throw new Error('Invalid API key');

  case 400:
  case 422:
    // Input problem — fix the request, don't retry
    console.error('Validation error:', data.field, data.message);
    throw new Error('Invalid input');

  case 429:
    // Rate limit — wait and retry
    const retryAfter = res.headers.get('Retry-After') || 60;
    await sleep(retryAfter * 1000);
    return retryRequest();

  case 500:
  case 502:
  case 503:
  case 504:
    // Server error — retry with backoff
    return retryWithBackoff();

  default:
    throw new Error(`Unexpected error: ${data.code}`);
}

Python example

import time
import requests

def make_request(url, headers, max_retries=3):
    for attempt in range(max_retries):
        res = requests.get(url, headers=headers)
        data = res.json()

        if res.ok:
            return data

        # Don't retry client errors (except 429)
        if 400 <= res.status_code < 500 and res.status_code != 429:
            raise Exception(f"Client error: {data['code']}")

        # Retry 429 and 5xx with backoff
        wait = (2 ** attempt) + (random.random() * 0.5)
        time.sleep(wait)

    raise Exception("Max retries exceeded")

Retry Logic

Retry logic is essential for production reliability. Use exponential backoff with jitter for all retryable errors.

What to retry

Exponential backoff formula

Standard backoff with jitter:

delay = min(base_delay * 2^attempt + random_jitter, max_delay)

# Example with base_delay = 1s, max_delay = 30s:
# Attempt 1: ~1-2 seconds
# Attempt 2: ~2-3 seconds
# Attempt 3: ~4-5 seconds
# Attempt 4: ~8-10 seconds
# Attempt 5: ~16-20 seconds

Related Documentation

• Authentication — Handle 401 authentication errors
• Rate Limits — Understand 429 rate limiting
• Webhooks — Get notified of async failures
• Sandbox Testing — Test error handling without charges