Error Handling

Error Response Format

When an error occurs, the API returns a consistent error response format:

{
  "success": false,
  "error": "Error Type",
  "message": "Human readable error message",
  "timestamp": "2024-01-15T09:30:00+00:00",
  "debug": {
    // Additional debug information (only in debug mode)
  }
}

HTTP Status Codes

The API uses standard HTTP status codes to indicate the success or failure of requests:

Status Code	Meaning	Description	Action Required
200	OK	Request successful	None
400	Bad Request	Invalid request parameters	Check request format and parameters
401	Unauthorized	Invalid or missing authentication	Check API key and headers
403	Forbidden	Insufficient permissions	Contact administrator for access
404	Not Found	Endpoint or resource not found	Check URL and resource ID
405	Method Not Allowed	HTTP method not supported	Use correct HTTP method (GET, POST, etc.)
429	Too Many Requests	Rate limit exceeded	Wait before retrying (see Retry-After header)
500	Internal Server Error	Server error occurred	Retry request or contact support
502	Bad Gateway	Server communication error	Retry request
503	Service Unavailable	Service temporarily unavailable	Retry after some time

Common Error Scenarios

Invalid API Key (401 Unauthorized)

{
  "success": false,
  "error": "Unauthorized",
  "message": "Invalid API key",
  "timestamp": "2024-01-15T09:30:00+00:00"
}

Solution: Verify your API key is correct and included in the X-Api-Key header.

Invalid Parameters (400 Bad Request)

{
  "success": false,
  "error": "Bad Request",
  "message": "Invalid parameter: per_page must be between 1 and 100",
  "timestamp": "2024-01-15T09:30:00+00:00"
}

Solution: Check the parameter documentation and ensure all values are within valid ranges.

Resource Not Found (404 Not Found)

{
  "success": false,
  "error": "Not Found",
  "message": "Client with ID 99999 not found",
  "timestamp": "2024-01-15T09:30:00+00:00"
}

Solution: Verify the resource ID exists and you have permission to access it.

Error Handling Best Practices

Always Check HTTP Status Codes

const response = await fetch(apiUrl, options);

if (!response.ok) {
    const errorData = await response.json();
    console.error('API Error:', errorData.message);
    
    // Handle specific error types
    switch (response.status) {
        case 401:
            // Redirect to login or refresh token
            break;
        case 429:
            // Implement retry logic with backoff
            break;
        case 500:
            // Show user-friendly error message
            break;
        default:
            // Handle other errors
    }
}

Implement Retry Logic

async function apiRequestWithRetry(url, options, maxRetries = 3) {
    for (let i = 0; i < maxRetries; i++) {
        try {
            const response = await fetch(url, options);
            
            if (response.ok) {
                return response;
            }
            
            // Don't retry client errors (4xx), only server errors (5xx)
            if (response.status < 500) {
                throw new Error(`HTTP ${response.status}: ${response.statusText}`);
            }
            
        } catch (error) {
            if (i === maxRetries - 1) throw error;
            
            // Wait before retrying (exponential backoff)
            await new Promise(resolve => setTimeout(resolve, Math.pow(2, i) * 1000));
        }
    }
}

Log Errors for Debugging

try {
    const response = await fetch(apiUrl, options);
    const data = await response.json();
    
    if (!data.success) {
        console.error('API Error:', {
            url: apiUrl,
            status: response.status,
            error: data.error,
            message: data.message,
            timestamp: data.timestamp
        });
    }
    
} catch (error) {
    console.error('Network Error:', error);
}

Getting Help

If you continue to experience issues:

Check the changelog for recent API changes
Review the code examples for proper implementation
Contact your system administrator with the error details
Include the request URL, headers, and full error response when reporting issues