HTTP Status Codes for the Numbers REST API

The following HTTP status codes are used by the Numbers REST API.

Additional codes might be added in the future. If you encounter a code that is not on this list, please consult the HTTP error codes for a definition.

Looking for provisioning or 10DLC codes?

Provisioning error codes are here. And 10DLC error codes are found here.

2xx - Success

Any 2xx response is considered a successful response. Response bodies will differ depending on the request. The Numbers 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 a phone number search.

Copy
Copied
 {
  "phoneNumber": "+12025550134",
  "projectId": "51bxxxxx-f2xx-4cxx-89xx-a1ed0ffxxxxx",
  "displayName": "string",
  "regionCode": "US",
  "type": "MOBILE",
  "capability": [
    "SMS"
  ],
  "money": {
    "currencyCode": "USD",
    "amount": "2.00"
  },
  "paymentIntervalMonths": 0,
  "nextChargeDate": "2022-08-24T14:15:22Z",
  "expireAt": "2022-08-24T14:15:22Z",
  "smsConfiguration": {
    "servicePlanId": "82bxxxxx74924bd687efxxxxx2f20xxx",
    "scheduledProvisioning": {
      "servicePlanId": "82bxxxxx74924bd687efxxxxx2f20xxx",
      "status": "WAITING",
      "lastUpdatedTime": "2022-08-24T14:15:22Z",
      "campaignId": "string",
      "errorCodes": []
    },
    "campaignId": "string"
  },
  "voiceConfiguration": {
    "appId": "string",
    "scheduledVoiceProvisioning": {
      "appId": "string",
      "status": "WAITING",
      "lastUpdatedTime": "2022-08-24T14:15:22Z"
    },
    "lastUpdatedTime": "2022-08-24T14:15:22Z"
  }
 }

201

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

4xx - User errors

400 level 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.

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

Responses with status 400 Bad Request and 403 Forbidden will present a JSON object in the body explaining the error. It has the following structure:

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

This is a sample of a 400 error utilizing the code and text fields to provide more info.

Copy
Copied
{
   "code": "syntax_invalid_json",
   "text": "The JSON in the request is invalid or doesn't conform to the API specification. "
}

400 - Bad request

The request doesn't conform to the Numbers 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.

  • 400 - INVALID_ARGUMENT . The reasoning will depend on the endpoint.

    When renting a new number, the phoneNumber, smsConfiguration.servicePlanId, or perhaps voiceConfiguration.appId is not valid.

    When searching for a number, it means that the pageSize, pageToken, numberPattern or orderBy fields are potentially not valid.

  • 400 - FAILED_PRECONDITION . Reasons for a failed precondition are: the project does not have enough credit to activate a number, supporting documentation (for US 10DLC numbers) is missing, or that the account currency is not supported.

401 - Unauthorized

Authentication token is invalid.

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 project ID.

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. 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 - 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 - PERMISSION_DENIED Improper credentials were used. Be sure your projectId , username and password are correct.
See a sample
Copy
Copied
{
   "error": {
     "code": 403,
     "message": "",
     "status": "PERMISSION_DENIED",
     "details": [ ]
     }
}

404 - Not found

The path is invalid or no resource exists with the given ID. Or, an available number could not be found.

405 - Method not allowed

The path is valid but not for this method.

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 Numbers API

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

  1. Check that the HTTP request is authenticated correctly .
  2. Ensure you're using all of the required parameters.
  3. If you have multiple project IDs, check that the project ID selected matches the credentials in your call .
  4. Check that it's not a regulatory issue. See our Country Information page for details on each country.
  5. If you're in the US, using the Numbers API for anything other than simple testing (using a verified number in the Customer Dashboard ), you'll need a 10DLC number . Learn more about 10DLC numbers .
  6. Your free testing balance may have run out. Time to upgrade !

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:

Still having trouble?

We're here to help! Reach out to your account manager for further assistance on error management.

Additional resources

Was this page helpful?
SecurityPrivacyLegal & ComplianceCookie Statement
© 2022 Sinch. All rights reserved.