Overview
The Aifano API uses standard HTTP status codes to indicate the success or failure of a request. All error responses include a JSON body with anerror field describing the issue.
Error Response Format
HTTP Status Codes
Success
Client Errors
Server Errors
Common Errors
Authentication Errors
Input Errors
Credit Errors
Processing Errors
Error Handling Best Practices
Always check the HTTP status code
Always check the HTTP status code
Don’t assume a
200 response. Check the status code before processing the response body.Implement retry logic for 5xx errors
Implement retry logic for 5xx errors
Server errors are usually transient. Retry with exponential backoff (e.g., 1s, 2s, 4s, 8s) up to a maximum number of attempts.
Use async endpoints for large documents
Use async endpoints for large documents
If you’re getting
504 Gateway Timeout errors, switch to the async variant of the endpoint to avoid timeouts.Monitor credit usage proactively
Monitor credit usage proactively
Track the
usage field in API responses to anticipate when you’re approaching your credit limit. Upgrade your plan before hitting the limit.Validate inputs before sending
Validate inputs before sending
Check that your file URL is accessible, the file type is supported, and required fields are present before making API calls.