Docs / Reference / API error codes and responses

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:

FieldTypeDescription
typestringThe type of error (see list below)
codeintegerAn error-specific code (see list below). Codes are stable and can be used in your error handling and when contacting support
messagestringA 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:

TypeDescription
api_errorThere was a problem with the API while processing the request
argument_errorThere was a problem with one of the arguments provided in the request
callback_errorThere was a problem with the callback URL provided
credentials_errorThere was a problem with the authentication credentials provided
media_errorThere was a problem with the media provided in the request (download, format, size, duration...)
plan_errorThere was a problem with the plan associated with the API key
request_errorThere was a problem with the request itself (endpoint, method, size, timeout...)
server_errorSightengine's servers encountered an error or a timeout
unknown_errorAn unknown error occurred
usage_limitThe 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.

CodeTypeHTTPMeaning
1credentials_error401Incorrect API user or API secret. Check the credentials shown on your dashboard
2credentials_error400Too many failed authentication attempts from your IP address. Requests from that IP are blocked for a few minutes
4argument_error400No media was provided in the request
1042argument_error400No file was found in the POST request. Send the file under the media key, with multipart/form-data encoding
1044argument_error400GET request without a url parameter
50argument_error400Unknown model name in the models parameter
51argument_error400The models parameter is missing
6media_error400The media URL could not be downloaded. Make sure the URL is correct and publicly reachable
12media_error400The server hosting the media returned 403 Forbidden. Make the media public, or upload the file instead of sending a URL
1201media_error400The media URL redirects. Provide the final URL
10media_error400Not an image or video, or format not supported
14media_error400The image file is too large
16media_error400The image is too small
710media_error400The video is too long for a synchronous call. Use the asynchronous video API instead
602argument_error400Text moderation: the lang parameter is required
604argument_error400Text moderation: the text exceeds the maximum length
701callback_error400Your callback URL returned an error status code
30usage_limit400Your usage limit has been reached
32usage_limit400Free plan: daily usage limit reached
33usage_limit429Request throttled (too many requests or operations per second). Retry with exponential backoff
35usage_limit400Unpaid invoices. Access is restored once they are paid
1103usage_limit400Liveness 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
43plan_error402The resource requires another plan
404request_error404This API path does not exist. Check the endpoint URL
413request_error413The file is too large for this endpoint
950server_error500Server error. Retry later with exponential backoff