API error codes and responses
Overview
When a request fails, the API returns a JSON body with "status": "failure" and an error object describing what went wrong.
The HTTP status code gives a first indication: 401 for invalid credentials, 402 for plan issues, 429 for throttling, 5xx for server errors. Most other errors, including usage limits, are returned with a 400 status. To decide how to handle an error, rely on error.type and error.code rather than on the HTTP status alone.
Failed requests are not billed: the number of operations of a failed request is always 0.
Response body
The response body will contain a JSON object with the following structure:
{
"status": "failure",
"request": {
"id": "req_jBS589QCnfWJmBKFZ1z71",
"timestamp": 1763657604.988901,
"operations": 0
},
"error": {
"type": "credentials_error",
"code": 1,
"message": "Incorrect API user or API secret"
}
}
The error object contains more details about the error:
| Field | Type | Description |
| type | string | The type of error (see list below) |
| code | integer | An error-specific code (see list below). Codes are stable and can be used in your error handling and when contacting support |
| message | string | A human-readable message describing the error. Messages may be reworded over time, so do not parse them |
In some cases errors may have no request object, only status and error.
Error types
The error.type field describes the type of error that occurred. The following error types are defined:
| Type | Description |
| api_error | There was a problem with the API while processing the request |
| argument_error | There was a problem with one of the arguments provided in the request |
| callback_error | There was a problem with the callback URL provided |
| credentials_error | There was a problem with the authentication credentials provided |
| media_error | There was a problem with the media provided in the request (download, format, size, duration...) |
| plan_error | There was a problem with the plan associated with the API key |
| request_error | There was a problem with the request itself (endpoint, method, size, timeout...) |
| server_error | Sightengine's servers encountered an error or a timeout |
| unknown_error | An unknown error occurred |
| usage_limit | The account cannot perform this request at the moment: quota or throttling limit reached, unpaid invoices, or a feature not included in the plan |
Handling errors
- Retry with exponential backoff on server_error, on api_error, and on code 33 (request throttled, HTTP 429). Spreading requests over time avoids throttling in the first place.
- Do not retry as is on argument_error, media_error, callback_error and request_error: the same request will fail again. Fix the request or the media first.
- Account-level errors (credentials_error, plan_error and most usage_limit errors) will keep failing until the credentials, plan, quota or invoices are sorted out from your dashboard. Code 2 (too many failed authentication attempts from your IP address) is lifted automatically after a few minutes.
Common error codes
Here are the error codes you are most likely to encounter. Other codes are specific to one endpoint or parameter, and their message explains the problem.
| Code | Type | HTTP | Meaning |
| 1 | credentials_error | 401 | Incorrect API user or API secret. Check the credentials shown on your dashboard |
| 2 | credentials_error | 400 | Too many failed authentication attempts from your IP address. Requests from that IP are blocked for a few minutes |
| 4 | argument_error | 400 | No media was provided in the request |
| 1042 | argument_error | 400 | No file was found in the POST request. Send the file under the media key, with multipart/form-data encoding |
| 1044 | argument_error | 400 | GET request without a url parameter |
| 50 | argument_error | 400 | Unknown model name in the models parameter |
| 51 | argument_error | 400 | The models parameter is missing |
| 6 | media_error | 400 | The media URL could not be downloaded. Make sure the URL is correct and publicly reachable |
| 12 | media_error | 400 | The server hosting the media returned 403 Forbidden. Make the media public, or upload the file instead of sending a URL |
| 1201 | media_error | 400 | The media URL redirects. Provide the final URL |
| 10 | media_error | 400 | Not an image or video, or format not supported |
| 14 | media_error | 400 | The image file is too large |
| 16 | media_error | 400 | The image is too small |
| 710 | media_error | 400 | The video is too long for a synchronous call. Use the asynchronous video API instead |
| 602 | argument_error | 400 | Text moderation: the lang parameter is required |
| 604 | argument_error | 400 | Text moderation: the text exceeds the maximum length |
| 701 | callback_error | 400 | Your callback URL returned an error status code |
| 30 | usage_limit | 400 | Your usage limit has been reached |
| 32 | usage_limit | 400 | Free plan: daily usage limit reached |
| 33 | usage_limit | 429 | Request throttled (too many requests or operations per second). Retry with exponential backoff |
| 35 | usage_limit | 400 | Unpaid invoices. Access is restored once they are paid |
| 1103 | usage_limit | 400 | Liveness detection is not included in your plan. Codes 1101 to 1105 work the same way for the other restricted features: Upload API, AI music detection, liveness detection, recapture detection and AI speech detection |
| 43 | plan_error | 402 | The resource requires another plan |
| 404 | request_error | 404 | This API path does not exist. Check the endpoint URL |
| 413 | request_error | 413 | The file is too large for this endpoint |
| 950 | server_error | 500 | Server error. Retry later with exponential backoff |