Our APIs follow standard HTTP status codes as defined in [Mozilla's HTTP status reference](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Status) (<https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Status>). Each API product may have specific error formats, but the underlying principles remain consistent. ### HTTP Status Codes Clients should handle responses according to the returned HTTP status code. The most common categories include: - **2xx Success** – The request was processed successfully. - **4xx Client Errors** – The request was incorrect (e.g., invalid parameters, authentication failure). - **5xx Server Errors** – The server encountered an issue while processing the request. For API-specific error details, refer to the relevant product's OpenAPI documentation ### Error response formats #### Newer APIs The current error handling relies on the SessionError returned in case of error { "code": "string", "description": "string", "details": "string", "statusCode": integer } Where: - **code** – A short error code (nullable), the list of short error codes is described in the product-specific documentation - **description** – A human-readable description of the error - **details** – Additional details about the error (nullable) - **statusCode** – The corresponding HTTP status code #### Older/Legacy products For older products error handling approaches may differ (v2 APIs, we’re actively migrating now, even 200 status code can be returned for error cases), but the most common error format is { "type": "string", "message": "string", } here - **type** – A high-level error category (nullable) - **message** – A human-readable error message ### Retry recommendations > To improve resilience when integrating with our API, we recommend implementing a structured retry mechanism for handling transient failures. The necessity of retries depends on the returned HTTP status code. #### Highly Recommended to Implement Retry > These status codes indicate temporary conditions where retrying after a delay will likely succeed: - **429** **Too Many Requests** / **425 Too Early** – The request was rate-limited. Implement retries with an increasing delay to comply with rate limits. - **502 Bad Gateway**, **503 Service Unavailable**, **504 Gateway Timeout** – The service is temporarily unavailable, possibly due to high load, scaling, maintenance, or other infrastructure update. #### Retry May Help > Some server-side errors may be temporary but could also indicate persistent issues. Retrying may resolve the issue, but persistent failures should be logged and reported: - **500 Internal Server Error** – May indicate an intermittent failure or an issue requiring investigation. #### Retry for Key Rotation Support > In some cases, authentication failures might occur due to API key rotation. If a request fails with: - **401 Unauthorized** / **403 Forbidden** – Might be caused by key rotation. Please retry with an alternative key if applicable. #### Recommended Retry Strategy > When implementing retries, follow these best practices (see also Microsoft recommendations <https://learn.microsoft.com/en-us/azure/architecture/patterns/retry>): - **Exponential Backoff** – Start with a short delay and increase exponentially. - **Initial Delay** – Typically 1 second, but scenario-dependent. - **Jitter (Randomization)** – Add randomness to avoid synchronized retry spikes. - **Max Retries** – Limit retries to 3-5 attempts to prevent excessive load. - **Timeout Handling** – Ensure overall retry duration aligns with expected API response times (e.g., a document analysis may take longer than a session status check). #### Circuit Breaker Mechanism > If retries continue to fail, implement a circuit breaker to halt further attempts and prevent unnecessary load. Log failures for monitoring and alerting to help diagnose recurring issues. Contact our support team if persistent failures occur.