Error Handling

All API responses follow a consistent format. Understanding error responses helps you build robust integrations.

Response Format

Success Response

All successful API responses follow this format:

{
  "success": true,
  "data": {
    // Response data here
  }
}

Error Response

All error responses follow this format:

{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable error message"
  }
}

HTTP Status Codes

Error Codes

Common error codes you may encounter:

Handling Errors

Client Errors (4xx)

Client errors indicate issues with your request that you can fix:

if (!response.ok) {
  const error = await response.json();
  
  if (response.status === 400) {
    // Validation error - check your request
    console.error('Validation error:', error.error.message);
  } else if (response.status === 401) {
    // Authentication error - check your API key
    console.error('Authentication error:', error.error.message);
  } else if (response.status === 403) {
    // Scope error - check your API key scopes
    console.error('Scope error:', error.error.message);
  } else if (response.status === 404) {
    // Resource not found
    console.error('Resource not found:', error.error.message);
  }
}

Server Errors (5xx)

Server errors are typically transient and should be retried:

if (response.status >= 500) {
  // Retry with exponential backoff
  const maxRetries = 3;
  for (let i = 0; i < maxRetries; i++) {
    await new Promise(resolve => setTimeout(resolve, Math.pow(2, i) * 1000));
    const retryResponse = await fetch(url, options);
    if (retryResponse.ok) {
      return retryResponse;
    }
  }
}

Validation Errors

When you receive a 400 Bad Request with VALIDATION_ERROR, the error message will indicate which fields are invalid:

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid email address format",
    "field": "email"
  }
}

Best Practices

1. Always check response status before parsing JSON
2. Handle specific error codes appropriately
3. Implement retry logic for 5xx errors and rate limits
4. Log errors with context for debugging
5. Never log API keys in error messages or logs
6. Validate input before sending requests to avoid validation errors