Error Reference

All API errors follow a consistent format with machine-readable codes and human-friendly messages.

Error Response Format

{
  "code": 400,
  "status": "error",
  "message": "Validation failed",
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "The title field is required",
    "details": {
      "field": "title",
      "constraint": "required"
    }
  }
}

HTTP Status Codes

Error Codes by Category

Authentication Errors (401)

Handling 401 errors:

async function handleRequest(path) {
  const res = await fetch(path, {
    headers: { 'Authorization': `Bearer ${token}` }
  });

  if (res.status === 401) {
    const { error } = await res.json();

    switch (error.code) {
      case 'TOKEN_EXPIRED':
        // Refresh and retry
        token = await refreshToken();
        return handleRequest(path);

      case 'REVOKED_API_KEY':
      case 'INVALID_API_KEY':
        // Need new API key - show error to user
        throw new Error('API key invalid. Please reconfigure.');

      default:
        throw new Error(error.message);
    }
  }

  return res.json();
}

Authorization Errors (403)

Resource Errors (404)

Note: Private resources return 404 (not 403) to avoid leaking information about their existence.

Rate Limit Errors (429)

Rate limit responses include helpful headers:

HTTP/1.1 429 Too Many Requests
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1707480000
Retry-After: 60
Content-Type: application/json

{
  "code": 429,
  "status": "error",
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Rate limit exceeded. Retry after 60 seconds.",
    "tier": "public_key"
  }
}

Handling rate limits:

async function fetchWithRetry(url, options, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    const res = await fetch(url, options);

    if (res.status === 429) {
      const retryAfter = res.headers.get('Retry-After') || 60;
      console.log(`Rate limited. Retrying in ${retryAfter}s`);
      await sleep(retryAfter * 1000);
      continue;
    }

    return res;
  }

  throw new Error('Max retries exceeded');
}

Validation Errors (400)

Server Errors (500, 503)

Handling server errors:

async function fetchWithBackoff(url, options) {
  const delays = [1000, 2000, 4000, 8000]; // Exponential backoff

  for (const delay of delays) {
    try {
      const res = await fetch(url, options);

      if (res.status >= 500) {
        await sleep(delay);
        continue;
      }

      return res;
    } catch (err) {
      await sleep(delay);
    }
  }

  throw new Error('Service unavailable');
}

Complete Error Code List

For programmatic error handling, here are all error codes:

type ErrorCode =
  // General
  | 'UNKNOWN_ERROR'
  | 'INTERNAL_ERROR'
  | 'INVALID_REQUEST'
  | 'UNAUTHORIZED'
  | 'FORBIDDEN'
  | 'NOT_FOUND'
  | 'CONFLICT'
  | 'VALIDATION_ERROR'
  | 'RATE_LIMIT_EXCEEDED'
  | 'SERVICE_UNAVAILABLE'

  // Authentication
  | 'INVALID_CREDENTIALS'
  | 'TOKEN_EXPIRED'
  | 'TOKEN_INVALID'
  | 'INSUFFICIENT_PERMISSIONS'
  | 'ACCOUNT_SUSPENDED'
  | 'ACCOUNT_NOT_VERIFIED'

  // Resources
  | 'ACCOUNT_NOT_FOUND'
  | 'LISTING_NOT_FOUND'
  | 'PUBLICATION_NOT_FOUND'
  | 'MEDIA_NOT_FOUND'
  | 'STORE_NOT_FOUND'

  // Validation
  | 'FIELD_REQUIRED'
  | 'FIELD_INVALID'
  | 'FIELD_TOO_LONG'
  | 'FIELD_TOO_SHORT'
  | 'INVALID_EMAIL'
  | 'INVALID_UUID'
  | 'INVALID_URL'

  // Business Logic
  | 'LIMIT_EXCEEDED'
  | 'OPERATION_NOT_ALLOWED'
  | 'RESOURCE_LOCKED'
  | 'DEPENDENCY_EXISTS'
  | 'DUPLICATE_OPERATION';