Sinch uses conventional HTTP codes to indicate the success or failure of an API request.
Generally, a 2xx code indicates success. 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 standard HTTP codes, we provide a Message field to help you understand in plain text what went wrong.
A summary of the HTTP error code and error type.
The HTTP error code.
A simple description of the cause of the error.
If applicable, a reference ID for support to use with diagnosing the error.
The Sinch API can throw the following HTTP codes:
Any 2xx response is considered a successful response. Response bodies will differ depending on the request.
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:
A 40001 error is a parameter validation error. It means you have used the wrong method for the request. You can fix this by using the correct method.
{
"errorCode": 40001,
"message": "Invalid parameters: {result.Message}"
}A 40002 error is a missing parameter error. It means there is a missing required parameter in the request. This error generally contains the missing parameter in the error message. You can fix this by providing the missing parameter.
{
"errorCode": 40002,
"message": "Bad request: {result.Message}" // e.g.:"Bad request: TTS callout information missing"
}A 40004 error is an invalid authorization key error. It means the application key you are using for the request is invalid.
{
"errorCode": 40004,
"message": "Bad request: Application key is invalid"
}A 40005 error is a number missing leading plus error. It means that a phone number included in the request is not in the proper format and is missing the leading plus (+) sign.
{
"errorCode": 40005,
"message": "Bad request: Phone number missing leading plus (+)"
}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:
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."
}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."
}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."
}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:
A 40200 error is an insufficient credit error. It means that your account does not have sufficient credit to make the request. You can fix this by adding more credit to your account.
{
"errorCode": 40200,
"message": "Not enough credit."
}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. The following examples all show different types of 403 errors:
The 40300 error indicates a forbidden request. The Voice API may return this error in various situations, including:
- The specified resource 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": "result.Message //(result.Result == ServiceReply.Forbidden)"
}404 errors concern missing resources. For example, if the requested resource can't be found. The following example shows a 404 error:
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.
{
"errorCode": 40400,
"message": "Requested resource was not found."
}This error can be returned in one case:
- Reference specified in the request is a duplicate
{
"errorCode": 40900,
"message": "Reference already defined."
}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:
This error is related to misconfiguration of the Voice app in the Build Dashboard
{
"errorCode": 42200,
"message": "Application name has not been configured."
}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."
}A 42202 error is an invalid callback response error. If you receive this error it means that the response you're sending back to a callback event request is not a valid response. Look at the Callback API documentation for information about the valid responses for each callback event type.
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:
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."
}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.
{
"errorCode": 50000,
"message": "Internal server error."
}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.
This error means that service is temporarily down. Try again later.
{
"errorCode": 50300,
"message": "Service is temporarily unavailable, please try again later."
}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."
}When making phone calls with the Voice API there a few steps in the process to look first if you are experiencing errors:
- If you code using a Sinch helper library (SDK), ensure the dependencies are available and referenced correctly.
- Check that the HTTP request is authenticated correctly.
- If making an outbound call, check if it rings on the phone.
- Once the call is answered, check that you receive a request to the the callback URL you have specified.
- Check that SVAML returned from the callback event is parsed and executed.
Each of the above steps could have an issue, problems ranging from network outage to invalid SVAML.
To help you pinpoint the problem here are a few pointers:
Below are a few things to check if the call never rings on the phone.
- Check the number to make sure it's the right number and formatted the correct way, including the
+and country code. - Look at the error message you received. If you don't have access to those (maybe it's happening in production) try to make a simple call to the phone number using the same application key and secret.
Balance is too low
Solution: Add more money to your account.
Too many calls
IN_PROGRESSSolution: Contact your account manager if you need to make more than 10 calls concurrently.