Error Handling

Understand API error responses and implement robust error handling in your integrations.

Error Response Format

When a request fails, the API returns a structured error response:

{
    "success": false,
    "error": {
        "code": "PRODUCT_NOT_FOUND",
        "message": "Product with ID 999 was not found",
        "details": "The specified product does not exist or belongs to another organization"
    },
    "timestamp": "2024-12-25T12:00:00Z"
}

HTTP Status Codes

Error Codes Reference

This table provides a quick reference of all error codes used across the API:

Authentication Errors (401)

Validation Errors (400)

Resource Errors (404)

Server Errors (500)

Best Practices

Error Handling

• Always check the success field before processing response data
• Use error codes (not messages) for programmatic error handling
• Log error responses for debugging, including the timestamp
• Display user-friendly messages based on error codes

Token Management

• Store tokens securely (never in localStorage for sensitive apps)
• Set a timer to refresh tokens 2-3 minutes before expiration
• Handle INVALID_TOKEN by redirecting to login

Retry Logic

• Implement exponential backoff for 500 errors
• Do not retry 400/401/404 errors automatically
• Set a maximum retry count (3-5 attempts)