Errors

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.
status
string

A summary of the HTTP error code and error type.

errorCode
string

The HTTP 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 throw the following HTTP codes:

2xx - Success

Any 2xx response is considered a successful response. Response bodies will differ depending on the request.

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

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.

{
  • "status": "400 ParameterValidation",
  • "errorCode": 40001,
  • "message": "Method needs to be `ttsCallout`, `conferenceCallout`, or `customCallout`"
}

40002

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.

{
  • "status": "400 MissingParameter",
  • "errorCode": 40002,
  • "message": "Bad request; method is missing a parameter"
}

40003

A 40003 error is an invalid request error.

{
  • "status": "400 InvalidRequest",
  • "errorCode": 40003,
  • "message": "Request data missing"
}

40004

A 40004 error is an invalid authorization key error. It means the application key you are using for the request is invalid.

{
  • "status": "400 InvalidAuthorizationKey",
  • "errorCode": 40002,
  • "message": "Invalid authorization key"
}

40005

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.
{
  • "status": "400 NumberMissingLeadingPlus",
  • "errorCode": 40002,
  • "message": "Phone number missing leading plus sign"
}

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.

{
  • "status": "401 AuthorizationHeader",
  • "errorCode": 40100,
  • "message": "Authorization header missing, illegal or invalid"
}

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.
{
  • "status": "401 TimestampHeader",
  • "errorCode": 40101,
  • "message": "X-Timestamp request header invalid or missing"
}

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.

{
  • "status": "401 MissingParameter",
  • "errorCode": 40102,
  • "message": "Request has invalid signature"
}

40103

{
  • "status": "401 AlreadyAuthorized",
  • "errorCode": 40103,
  • "message": "User is already authorized"
}

40104

{
  • "status": "401 MissingParameter",
  • "errorCode": 40104,
  • "message": "The request was not authorized and signed with the application secret"
}

40105

{
  • "status": "401 Expired",
  • "errorCode": 40105,
  • "message": "The request for authorization has expired"
}

40107

{
  • "status": "401 InvalidAuthorization",
  • "errorCode": 40107,
  • "message": "Wrong type of auth used or invalid password or key"
}

40108

{
  • "status": "401 InvalidCredentials",
  • "errorCode": 40108,
  • "message": "Credentials provided are invalid"
}

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

{
  • "status": "402 PaymentRequired",
  • "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. The following examples all show different types of 403 errors:

40300

{
  • "status": "403 ForbiddenRequest",
  • "errorCode": 40300,
  • "message": "Resource destination is forbidden"
}

40301

{
  • "status": "403 InvalidScheme",
  • "errorCode": 40301,
  • "message": "Invalid authorization scheme"
}

40302

{
  • "status": "401 InsufficientPrivileges",
  • "errorCode": 40302,
  • "message": "Privileges are insufficient to access the resource"
}

40303

{
  • "status": "401 RestrictedAction",
  • "errorCode": 40303,
  • "message": "Requested action is restricted"
}

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

{
  • "status": "404 ResourceNotFound",
  • "errorCode": 40400,
  • "message": "Requested resource not found"
}

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

{
  • "status": "409 RequestConflict",
  • "errorCode": 40900,
  • "message": "The request could not be completed due to a conflict with the current resource"
}

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

{
  • "status": "401 InvalidCredentials",
  • "errorCode": 40108,
  • "message": "Credentials provided are invalid"
}

42201

{
  • "status": "401 InvalidCredentials",
  • "errorCode": 40108,
  • "message": "Credentials provided are invalid"
}

42202

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.

{
  • "status": "401 InvalidCredentials",
  • "errorCode": 40108,
  • "message": "Credentials provided are invalid"
}

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

{
  • "status": "429 CapacityExceeded",
  • "errorCode": 42900,
  • "message": "The number of requests has exceeded capacity"
}

42901

{
  • "status": "429 VelocityConstraint",
  • "errorCode": 42901,
  • "message": "The number of requests has exceeded velocity constraint"
}

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

{
  • "status": "500 InternalError",
  • "errorCode": 50000,
  • "message": "General error; try submitting request again"
}

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

{
  • "status": "503 TemporaryDown",
  • "errorCode": 50500,
  • "message": "Service temporarily unavailable"
}

50301

{
  • "status": "503 ConfigurationError",
  • "errorCode": 50301,
  • "message": "Server configuration error; try submitting request again"
}

Troubleshooting the Voice API

When making phone calls with the Voice 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 outbound call, check if it rings on the phone.
  4. Once the call is answered, check that you receive a request to the the callback URL you have specified.
  5. 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:

The phone number I call never rings

Below are a few things to check if the call never rings on the phone.

  1. Check the number to make sure it's the right number and formatted the correct way, including the + and country code.
  2. Look at the error message you received. If you dont 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.

Common errors

  • Balance is too low

    Solution: Add more money to your account.

  • Too many calls IN_PROGRESS

    Solution: Contact your account manager if you need to make more than 10 calls concurrently.

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