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.

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.

{
"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.

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

400 errors generally concern the construction or format of the request you submitted. For example, it may be missing required parameters or you could be using the wrong parameter in a request.

{
   "error": {
       "code": 400,
       "message": "parsing field \"type\": \"XXX\" is not a valid value",
       "status": "INVALID_ARGUMENT",
       "details": [ ]
   }
}

In addition to the standard HTTP codes, responses may also display code and text fields to help you understand what went wrong.

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

400 - Bad request

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

• 400 - syntax_constraint_violation means that the request body doesn't fulfill all of the constraints set by the API. So if a required field is missing, you'll see this error. All required fields are marked in red text in the API reference.
• 400 - syntax_invalid_json means that the JSON in the request is invalid or doesn't conform to the API specification. Most online JSON validators should make quick work of resolving this error!
• 400 - syntax_invalid_parameter_format means that the format of a field value is invalid. For example, if a MSISDN (phone number) is not correctly formatted. If you, for example, forgot to add the area code, this error will appear.

Most often, this is because a required parameter isn't in your request, a typo, or even a formatting error in the code itself.

401 - Unauthorized

Authentication token is invalid for this service plan.

Everything about your request is likely valid, but the token is not. 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 give it another try!

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.

• 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.
• 403 - The missing_callback_url code means that a callback has been requested, but no URL is provided. Add a callback URL to your request. Learn how here .
• 403 - unknown_campaign The campaign ID doesn't match the specified originator. This error will appear on endpoints that allow the campaign_id parameter. Double check your campaign ID and give it another go!
• 403 - unknown_group means that a referenced group ID is unknown to the API. This could happen if the ID is invalid or if the group has been deleted.

404 - Not found

The path is invalid or no resource exists with the given ID.

405 - Method not allowed

The path is valid but not for this method. For example, if you tried to send a delete method on an inbound endpoint, it would not work since inbound methods are retrieving what has already been sent.

415 - Unsupported media type

The Content-Type header is missing or unsupported. Most operations expect application/json.

429 - Too many requests

The user or path has too many outstanding requests.

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

An unexpected internal error occurred and the request wasn't processed. Contact your account manager for more information.

503 Service Unavailable

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.

Troubleshooting the SMS REST API

Here are few things you can do if you encounter an error with the SMS REST API:

1. Check that the HTTP request is authenticated correctly .
2. Ensure you're using all of the required parameters.
3. If you're using one of our SDKs, ensure the dependencies are available and referenced correctly.
4. Check that your callback URL is correctly configured and working properly.
5. If you have multiple service plans, check that the service plan ID selected matches the credentials in your call .
6. If you're testing, make sure the number you're testing with is verified in the Sinch Customer Dashboard .
7. Ensure you're sending from a Sinch number . Either your test number or a rented number.

Useful support articles

We also have a library of help articles that can point you in the right direction. Here are a few that may be useful for troubleshooting:

• Why wasn't my message delivered?
• What features and restrictions are there for sending messages to different countries?
• My delivery receipt shows successful, but my message did not deliver – what’s going on?
• Why is my sender ID not delivering?
• How can you check the delivery statuses of your SMS?

Find SMPP error info here. And find 10DLC (US number related) error info here.