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.

200

OK. The request was successful.

See a sample

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

Copy

Copied

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

201

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

See a sample

This is a sample for a successfully created group.

Copy

Copied

{
   "id": "01FC66621VHDBN119Z8PMV1QPU",
   "name": "My new customers",
   "size": 2,
   "created_at": "2019-08-24T14:15:22Z",
   "modified_at": "2019-08-24T14:15:22Z",
   "child_groups": [
       "01FC66621VHDBN119Z8PMV1AHY"
   ],
   "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

Copy

Copied

{
   "code": "missing_callback_url",
   "text": "Requesting delivery report without any callback URL."
}

Note:

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 https://jsonlint.com/ 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: Through the dashboard as explained here 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: wait until the API resource is ready to consume data and send another request 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