Errors
How the API reports errors and how to handle them.
Errors
The InfraRed API uses standard HTTP status codes and returns a JSON body for errors.
Error response format
When an error occurs, the response body includes an error object with:
- code – Machine-readable error code
- message – Human-readable description
- field – Optional; the request field that caused the error, when applicable
HTTP status codes
- 400 Bad Request – Invalid request (e.g. validation failure, malformed body)
- 401 Unauthorized – Missing or invalid API key
- 403 Forbidden – Valid credentials but insufficient permissions
- 404 Not Found – Resource or endpoint not found
- 413 Payload Too Large – Request body exceeds size limits
- 429 Too Many Requests – Rate limit exceeded
- 500 Internal Server Error – Server error; retry with backoff
- 504 Gateway Timeout – Upstream timeout; retry later
Include the Request-Id header from the response when contacting support.
Blurry documents
Document extraction returns 400 Bad Request with the error code document_too_blurry when out-of-focus or motion blur makes the requested information unreliable to extract. Ask the user for a clearer image or scan before retrying the request.
Error codes
| Code | HTTP status | Description |
|---|---|---|
| document_base64_payload_invalid | 400 | This error code indicates that the document base64 payload is invalid |
| document_content_type_not_supported | 400 | This error code indicates that the document content type is not supported |
| document_not_of_type | 400 | This error code indicates that the document is not of the expected type |
| document_too_blurry | 400 | This error code indicates that the document is too blurry to extract reliably |
| document_too_large | 400 | This error code indicates that the document is too large |
| document_url_unreachable | 400 | This error code indicates that the document URL is unreachable |
| field_value_invalid | 400 | This error code indicates that value supplied for the field is invalid. |
| request_body_invalid | 400 | This error code indicates that the request body is invalid. |
| required_field_missing | 400 | This error code indicates that the request is missing a required field. |
| api_key_invalid | 401 | This error code indicates that the API key is invalid. |
| api_key_not_provided | 401 | This error code indicates that the API key was not provided in the request headers. |
| wallet_credit_not_enough | 402 | This error code indicates that the user's wallet has insufficient credits to perform the action. |
| request_body_too_large | 413 | This error code indicates that the request body is too large. The maximum allowed size is 5MB. |
| internal_server_error | 500 | This error code indicates that something went wrong with our servers. |
| service_temporary_unavailable | 503 | This error code indicates that the service is temporarily unavailable. |