Errors

Sinch uses conventional HTTP codes to indicate the success or failure of an API request.

Generally, a 2xx code indicates success. 3xx codes are essential part of data verification process. Codes in the 4xx range indicate an error that failed because of information you provided in the request (authentication failed, a required field was missing, or some other parameter was invalid are all examples). Codes in the 5xx range are rare errors on the Sinch servers that you as a developer usually can't do anything about.

In addition to the error codes, we provide a Message field to help you understand in plain text what went wrong.
errorCode
string

The Sinch error code.

message
string

A simple description of the cause of the error.

reference
string

If applicable, a reference ID for support to use with diagnosing the error.

HTTP Codes

The Sinch API can return the following HTTP codes:

2xx - Success

Any 2xx response is considered a successful response. Response bodies will differ depending on the request. Refer to documenation of particular endpoint for details.

3xx - Redirect

Some Data Verification endpoints may return HTTP 3xx (redirection) status codes. It is essential to follow these redirects to ensure proper execution of the business process. Only bypass the redirect if you have a specific and justified reason for doing so.

400 - BadRequest

400 errors generally concern the construction or format of the request you submitted. For example, missing required parameters or the using the wrong parameter in a request. The following examples all show different types of 400 errors:

40001

The 40001 error indicates a parameter validation failure. This error occurs when one or more parameters in the request are invalid.

{
  • "errorCode": 40001,
  • "message": "Number +4813 is invalid. Too short."
}

The error message provides specific details about issues in the request body.

Examples of common problems include:

  • Missing + sign in a phone number,
  • Number that is too short,
  • Missing required field in the request.

These issues are typically easy to fix by following the guidance provided in the message field.

40003

The 40003 error indicates an invalid request. This error occurs when the request cannot be processed, despite all parameters being syntactically valid.

{
  • "errorCode": 40003,
  • "message": "Invalid identity or code."
}

In some cases, resolving a 40003 error is straightforward, similar to fixing a 40001 error. In other cases, it may involve more complex issues, such as:

  • Using a phone number that is syntactically valid but not a valid target for SMS delivery,
  • Attempting to perform subsequent steps (e.g., reporting or status checking) for a verification process that was never initiated,
  • Reporting an invalid verification code.

While these errors can generally be corrected by the caller, they may require changes to the business logic or process flow. Additionally, in some scenarios — particularly when reporting an invalid code — these errors may represent valid and expected responses.

401 - Unauthorized

401 errors concern authorization and access. For example, if you do not provide valid credentials in your request. The following examples all show different types of 401 errors:

40100

A 40100 error is an authorization header error. It means the authorization header is missing, illegal, or invalid. You can fix this by providing a valid authorization header.

{
  • "errorCode": 40100,
  • "message": "Invalid authorization header"
}

40101

A 40101 error is a timestamp header error. It means that the x-timestamp header is invalid or missing. You can fix this by providing a valid x-timestamp header.
{
  • "errorCode": 40101,
  • "message": "X-Timestamp required"
}

40102

A 40102 error is an invalid signature error. It means that the signature in your signed request authentication is invalid or missing. You can fix this by providing a valid signature in your signed request.

{
  • "errorCode": 40102,
  • "message": "Invalid signature"
}

40104

A 40104 error is an authorization required error. It means that your request is missing authentication.

{
  • "errorCode": 40104,
  • "message": "Authorization required"
}

40107

A 40107 error is an invalid authorization error. It means some part of your authentication is incorrect. You can fix this by ensuring your authorization configuration is configured correctly.

{
  • "errorCode": 40107,
  • "message": "Invalid authorization"
}

402 - PaymentRequired

402 errors concern payment or credit. For example, if your does not have the necessary credit to perform the action. The following example shows a 402 error:

40200

{
  • "errorCode": 40200,
  • "message": "Not enough credit"
}

403 - Forbidden

403 errors concern lack of permission. For example, if you as a user do not have the necessary privileges or permissions to perform the action.

This error can also be returned when URL path is incorrect. Check the URL and ensure you are using the correct endpoint.

The following examples all show different types of 403 errors:

40300

The 40300 error indicates a forbidden request. The Verification API may return this error in various situations, including:

  • Data Verification is not available for the requested destination,
  • The destination number has been blacklisted by internal fraud detection systems.

These errors cannot be resolved by the user. If a 40300 error is encountered, please contact support for assistance.

{
  • "errorCode": 40300,
  • "message": "Identity is blacklisted."
}

40303

The 40303 error indicates a restricted action. This error typically occurs when the requested action is not permitted due to one of the following reasons:

  • The action was explicitly denied by a callback,
  • The action triggered internal anti-fraud mechanisms.
{
  • "errorCode": 40303,
  • "message": "Callback URL must be set when using public authorization method."
}

In some scenarios, the 40303 error can be resolved by the user. Examples include:

If the 40303 error occurs in other cases, please contact support for assistance. For security reasons, specific triggers related to anti-fraud systems are not disclosed.

404 - NotFound

404 errors concern missing resources. For example, if the requested resource can't be found. The following example shows a 404 error:

40400

{
  • "errorCode": 40400,
  • "message": "Requested resource was not found."
}

This error can be returned in various circumstances, including:

  • Attempting to perform actions such as reporting or checking the status of a verification that was not initiated (similar to the 40003 error),
  • Calling these endpoints with partially invalid parameters (e.g., querying a status endpoint with a correct identity but an incorrect verification method),
  • Querying various endpoints, such as those related to price lists, using incorrect parameters.

If this error is returned in other cases, contact support.

409 - Conflict

409 errors concern conflict errors due to race conditions or the requested resource being in an unexpected state. The following example shows a 409 error:

40900

This error can be returned in one case:

  • Reference specified in the request is a duplicate
{
  • "errorCode": 40900,
  • "message": "Reference already defined"
}

420 - Unprocessable Entity

420 errors concern not being able to process the request resource due to various factors. The following examples all show different types of 420 errors:

42200

This error is related to misconfiguration of Verification App in Sinch Dashboard.

{
  • "errorCode": 42200,
  • "message": "Application name has not been configured"
}

42201

The 42201 error indicates that there is no available route to the destination number. Consequently, Sinch is unable to send SMS messages, initiate calls, or perform other actions targeting the specified destination due to internal routing issues. This condition is classified as an internal routing error and is typically permanent, meaning the failure will persist unless the underlying routing problem is resolved by Sinch's internal systems.

{
  • "errorCode": 42201,
  • "message": "No route to destination."
}

429 - Too Many Requests

429 errors concern too many requests occuring within a specific period, either because of a technical limitation or account limitation. The following examples all show different types of 429 errors:

42900

This error occurs when rate limit is exceeded. It means that the number of requests sent to the API exceeds the allowed limit.

{
  • "errorCode": 42900,
  • "message": "Request capacity exceeded"
}

42901

This error occurs when verification of the same number is attempted too many times within a short period of time.

{
  • "errorCode": 42901,
  • "message": "Cannot initiate verification to the same number too quickly"
}

500 - Internal Server Error

500 errors are general server errors that are temporary and you usually can't do anything about. Try the request a little later or contact support if you receive this error repeatedly after a period of time.

50000

{
  • "errorCode": 50000,
  • "message": "Internal server error."
}

503 - Service Unavailable

503 errors are unvailable service errors that are temporary and you usually can't do anything about. Try the request a little later or contact support if you receive these errors repeatedly after a period of time.

50300

This error means that service is temporarily down. Try again later.

{
  • "errorCode": 50300,
  • "message": "Service is temporarily unavailable, please try again later."
}

50301

This error means that there is a misconfiguration in the Sinch system related to your account. Contact support to resolve this issue.

{
  • "errorCode": 50301,
  • "message": "Configuration error, please contact support."
}

Troubleshooting the Verification API

When making phone calls with the Verification API there a few steps in the process to look first if you are experiencing errors:

  1. If you code using a Sinch helper library (SDK), ensure the dependencies are available and referenced correctly.
  2. Check that the HTTP request is authenticated correctly.
  3. If making an SMS verification, check if the phone receives an SMS.

Each of the above steps could have an issue, problems ranging from network outage to invalid parameters.

Common errors

  • Balance is too low

    Solution: Add more money to your account.

We'd love to hear from you!
Rate this content:
Still have a question?
 
Ask the community.
SecurityPrivacyLegal & ComplianceCookie Statement
© 2025 Sinch. All rights reserved.