# 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. ## 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 documentation 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. ```json 40001 Error { "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. ```json 40003 Error { "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](/docs/verification/api-reference/authentication) header. ```json 40100 Error { "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`](/docs/verification/api-reference/authentication/application-signed-request#timestamp) header. ```json 40101 Error { "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](/docs/verification/api-reference/authentication/application-signed-request) in your signed request. ```json 40102 Error { "errorCode": 40102, "message": "Invalid signature." } ``` #### 40104 A 40104 error is an authorization required error. It means that your request is missing authentication. ```json 40104 Error { "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. ```json 40107 Error { "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 ```json 40200 Error { "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. ```json 40300 Error { "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. ```json 40303 Error { "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: - The CallbackUrl is misconfigured, and the request is using [public authentication](/docs/verification/api-reference/authentication/public-authentication), - The verification request was explicitly denied by the [callback](/docs/verification/api-reference/authentication/public-authentication). 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 ```json 40400 Error { "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 ```json 40900 Error { "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](https://dashboard.sinch.com). ```json 42200 Error { "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. ```json 42201 Error { "errorCode": 42201, "message": "No route to destination." } ``` ### 429 - Too Many Requests 429 errors concern too many requests occurring 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. ```json 42900 Error { "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. ```json 42901 Error { "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 ```json 50000 Error { "errorCode": 50000, "message": "Internal server error." } ``` ### 503 - Service Unavailable 503 errors are unavailable 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. ```json 50300 Error { "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. ```json 50301 Error { "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](https://dashboard.sinch.com).