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": "Supplied SMS code invalid format / The SMS code is not valid. Maximum 10 characters. Valid characters: A-Z, a-z, 0-9, '-'"
}

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": "Endpoint parameter is missing."
}

40003

A 40003 error is an invalid request error. It means some element of the request was unable to be processed. Try ensuring the phone number is correct.

{
  • "status": "400 InvalidRequest",
  • "errorCode": 40003,
  • "message": "Phone number invalid"
}

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": "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.
{
  • "status": "401 AuthorizationHeader",
  • "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.

{
  • "status": "401 InvalidSignature",
  • "errorCode": 40102,
  • "message": "Invalid signature"
}

40104

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

{
  • "status": "401 AuthorizationRequired",
  • "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.

{
  • "status": "401 InvalidAuthorization",
  • "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

{
  • "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": "Seamless not available / Seamless verification not available for given destination"
}

40303

{
  • "status": "401 RestrictedAction",
  • "errorCode": 40303,
  • "message": "No verification method available"
}

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": "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

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

42201

{
  • "status": "422 Unavailable",
  • "errorCode": 42201,
  • "message": "Destination denied"
}

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": "Request capacity exceeded"
}

42901

{
  • "status": "429 VelocityConstraint",
  • "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

{
  • "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; 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
© 2024 Sinch. All rights reserved.