# 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](https://www.w3schools.com/tags/ref_httpmessages.asp) for a definition. Looking for provisioning or 10DLC codes? Provisioning and 10DLC error codes are found [here](/docs/numbers/api-reference/error-codes/provisioning-errors). ## 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. details summary See a sample This is a sample of the response for a phone number search. ```json { "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. details summary See a sample ```json { "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` | details summary See a sample This is a sample of a 400 error utilizing the `code` and `text` fields to provide more info. ```json { "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 Sinch Build 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. details summary See a sample ```json { "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](https://dashboard.sinch.com/account/details) for more information. ### 500 - Internal server error An unexpected internal error occurred and the request wasn't processed. [Contact your account manager](https://dashboard.sinch.com/account/details) 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](https://dashboard.sinch.com/account/details) 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](/docs/numbers/api-reference/authentication/basic). 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](https://dashboard.sinch.com/settings/access-keys). 4. Check that it's not a regulatory issue. See our [Country Information ](https://dashboard.sinch.com/sms/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 [Sinch Build Dashboard](https://dashboard.sinch.com/numbers/verified-numbers)), you'll need a [10DLC number](https://community.sinch.com/t5/10DLC/How-do-I-register-to-use-10DLC/ta-p/8857). [Learn more about 10DLC numbers](https://community.sinch.com/t5/10DLC/What-is-10DLC/ta-p/7845). 6. Your free testing balance may have run out. Time to [upgrade](https://dashboard.sinch.com/numbers/buy-numbers)! ### Useful support articles We also have [a library of help articles](https://community.sinch.com/t5/Numbers/ct-p/Numbers) that can point you in the right direction. Here are a few that may be useful for troubleshooting: - [How can I go live with my Sinch number?](https://community.sinch.com/t5/Virtual-Numbers/How-can-I-go-live-with-my-Sinch-number/ta-p/8656) - [How can I add a verified number to my account?](https://community.sinch.com/t5/Virtual-Numbers/How-can-I-add-a-verified-number-to-my-account/ta-p/8723) - [How can I get several numbers at once?](https://community.sinch.com/t5/Virtual-Numbers/How-can-I-get-several-numbers-at-once/ta-p/8641) Still having trouble? We're here to help! Reach out to your [account manager](https://dashboard.sinch.com/account/details) for further assistance on error management. ## Additional resources - Check out some [Voice API tutorials](/docs/voice/tutorials). - Sending SMS? Take a look at our [SMS REST API tutorials](/docs/sms/tutorials).