HTTP Status Codes for the SMS REST API

The Sinch SMS API returns an HTTP status and code each time a request is made.

Generally, a 2xx code indicates success. Codes in the 4xx range indicate an error due to information you provided in the request. Examples are if has authentication failed, a required field was missing, or some other parameter was invalid. Codes in the 5xx range are rare and typically indicate an error on our end.

Additional codes might be added in the future and if you encounter a code not in this list please consult the HTTP specification for a definition.

Looking for SMPP errors?

Find those here.

2xx - Success

Any 2xx response is considered a successful response. Response bodies will differ depending on the request. The SMS REST API will give a 200 or 201 code.


OK. The request was successful.

See a sample

This is a sample of the response for retrieving a specific message sent.

"id": "9dfn32n423kljklj234",
"from": "12345",
"to": [
"body": "Hello! How are you?",
"created_at": "2022-02-25T23:01:01Z",
"modified_at": "2022-02-25T23:01:01Z",
"canceled": false


Created. The POST request was successful and a new resource was created.

See a sample

This is a sample for a successfully created group.

   "id": "01FC66621VHDBN119Z8PMV1QPU",
   "name": "My new customers",
   "size": 2,
   "created_at": "2019-08-24T14:15:22Z",
   "modified_at": "2019-08-24T14:15:22Z",
   "child_groups": [
   "auto_update": {
       "to": 15551231234,
       "add": "string",
       "remove": "string"

4xx - User errors

4xx errors occur when the user sends a request which is invalid for some reason. This can include using the wrong credentials to access the API, or ommitting required parameters from a request. For most 4xx errors, you will get the standard response from the server. HTTP codes 400 and 403 are subdivided into codes. For 400 and 403, the REST API returns a specific response with the fields code and text:

Name Description JSON Type
code A code that can be used to programmatically recognize the error. string
text Human readable description of the error. Can be used for debugging. string
See a sample
   "code": "missing_callback_url",
   "text": "Requesting delivery report without any callback URL."


If you encounter a 404 error, the REST API does not return a response body.

400 - Bad request

The request doesn't conform to the API. The response body will likely provide one of the following reasons:

HTTP Response Code Description Troubleshooting tips
400 syntax_constraint_violation The request body doesn't fulfill all of the constraints set by the API. These include situations like
  • required field (marked in red in the API reference) missing.
  • request body is over the maximum allowed length
  • message is set to expire in the past
The text field should provide the information needed to identify the error.
400 syntax_invalid_json The JSON in the request is invalid or doesn't conform to the API specification. Use an online JSON validator such as to correct the syntax.
400 syntax_invalid_parameter_format The format of a field value is invalid. This could be an incorrectly formatted MSISDN (phone number) or a missing value, such as forgetting to add the area code. The text field should provide the information needed to identify the error.

401 - Unauthorized

HTTP Response Description Troubleshooting tips
401 Authentication token is invalid for this service plan. Try the following:
  • Log into the Customer Dashboard and double check that your token matches the corresponding service plan ID (or project ID in some cases).
  • If you are using OAuth 2.0, your access token may have expired. Generate a new one and try again.

403 - Forbidden

The request syntax is valid but can't be performed. This could be because a referenced resource doesn't exist. For example, attempting to retrieve a delivery report with an incorrect batch ID. We'll break down 403 errors further below.

HTTP Response Code Description Troubleshooting tips
403 blocked_account Indicates that your account has been blocked. Reach out to your account manager for further assistance.
403 illegal_number_type Illegal phone number type of MSISDN for a chosen region was used. Send to a different MSISDN.
403 missing_callback_url A callback has been requested, but no URL is provided. There are two ways to add a callback URL to your request:
  1. Through the dashboard as explained here
  2. Directly in the request body (this will only work for the particular SMS.)
403 unknown_group A referenced group ID is unknown to the API. This could happen if the ID is invalid or if the group has been deleted. Check the group ID in your request body belongs to an existing group and make sure you use a valid ID.

404 - Not found

HTTP Response Description Troubleshooting tips
404 The path is invalid or no resource exists with the given ID. Try the following:
  1. wait until the API resource is ready to consume data and send another request
  2. check whether the data might have been cleaned due to the retention policy

405 - Method not allowed

HTTP Response Description Troubleshooting tips
405 The path of the endpoint is valid but the request is using the wrong HTTP request method. For example, if you tried to send a DELETE request on an inbound endpoint, it would not work since inbound methods are retrieving what has already been sent. Check that the HTTP request method you are using matches the function of the endpoint you are trying to call.

415 - Unsupported media type

HTTP Response Description Troubleshooting tips
415 The Content-Type header is missing or unsupported. The SMS API uses application/json. Add the Content-Type header to the request.

429 - Too many requests

HTTP Response Description Troubleshooting tips
429 The user or path has too many outstanding requests. Try waiting for an interval between requests and sending requests at a slower rate.

5xx - Sinch errors

Errors that are of the 500 level are from our end. If you encounter one of these, reach out to your account manager for more information.

500 - Internal server error

HTTP Response Description Troubleshooting tips
500 An unexpected internal error occurred and the request wasn't processed. Try the request again. If you are still getting a 500 error contact your account manager for more information.

503 Service Unavailable

HTTP Response Description Troubleshooting tips
503 The service is unable to perform the request at this point. Most likely due to a required subsystem being unavailable. Contact your account manager for more information.

Further Troubleshooting

If you need more help troubleshooting, you can go to Troubleshooting the SMS REST API

We'd love to hear from you!
Rate this content:
Still have a question?
Ask the community.