Error codes
REST API reference for IMEILookup: error format and error codes.
Error Response Format
Application errors follow this JSON structure:
{
"message": "ERROR_CODE",
"statusCode": 400
}
The message field is an application error code, or an array of codes or validation messages, so handle both a string and an array. Some responses also include an error field with the HTTP status text. The statusCode field is the HTTP status. Requests rejected before they reach the API, for example by the edge network, can use a different format.
Error Codes Reference
INVALID_API_KEY (401) is returned only by GET /order/browser when the key in the URL is not recognised. A missing or empty key there returns 400 key should not be empty.
TAC_FAILED and INVALID_IMEI_PROVIDED (single and browser orders) and INVALID_IMEI (bulk orders) are identifier validation errors. See Identifiers for what each means and what is not yet confirmed.
Common Errors (all header-key endpoints)
| HTTP | Code | Meaning |
|---|---|---|
| 401 | INVALID_TOKEN | The key format is valid but the key is not recognised |
| 403 | LOGIN_AGAIN | The access-key header is missing, empty or not a valid key format |
| 401 | YOUR_IP_IS_NOT_PERMITED | Your IP is not permitted, login to dashboard and add your IP to the allow-list |
| 403 | YOU_ARE_NOT_ALLOWED | You are not allowed for this action |
| 403 | YOU_ARE_BLOCKED | You are blocked, contact admin |
| 403 | PENDING_FOR_APPROVAL | Your account is pending for approval |
GET /order — List Orders
| HTTP | Code | Meaning |
|---|---|---|
| 400 | PAGE_NUMBER_INVALID | Page number is invalid |
| 400 | PAGE_SIZE_INVALID | Page size is invalid |
| 400 | INVALID_PAGE_SIZE | Page size cannot exceed 5000 |
| 400 | ORDER_STATUS_INVALID | Order status not valid |
| 400 | INVALID_DATE_PROVIDED | Invalid date provided |
| 400 | SERVICE_ID_INVALID | Service ID not valid |
| 404 | SERVICE_NOT_FOUND | Service not found |
| 400 | SEARCH_MUST_BE_LIST | Search must be a list |
| 400 | FILTER_VALUE_INVALID | Filter value is invalid |
| 400 | INVALID_BATCH_NAME_FILTER | Invalid batch name filter |
| 400 | SUBUSERS_MUST_BE_LIST | Subusers must be a list |
| 400 | SUBUSERS_ARE_INVALID | Subusers are invalid |
| 400 | INVALID_SORT_VALUE | Invalid sort value |
| 400 | INVALID_ORDER_TYPE | Invalid order type |
| 403 | CANNOT_VIEW_HISTORY | You cannot view history, contact provider |
POST /order — Place Bulk Order
| HTTP | Code | Meaning |
|---|---|---|
| 400 | INVALID_IMEI | Invalid IMEI(s) provided |
| 400 | SERVICE_ID_MUST_BE_NUMBER | Service ID must be a number |
| 400 | INVALID_BATCH_NAME | Invalid batch name |
| 400 | BATCH_NAME_REQUIRED | Batch name is required |
| 400 | IMEI_MUST_BE_ARRAY | IMEIs must be provided in an array |
| 400 | IMEI_REQUIRED | IMEI is required |
| 403 | CREDIT_LIMIT_REACHED | Credit limit reached |
| 403 | LOW_CREDIT | Low credit |
| 403 | SERVICE_LIMIT_EXCEEDED | Service limit exceeded |
| 404 | SERVICE_NOT_FOUND | Service not found |
| 405 | SERVICE_IS_DISABLED | Service is disabled |
POST /order/single — Place Single Order
| HTTP | Code | Meaning |
|---|---|---|
| 400 | TAC_FAILED | TAC validation failed |
| 400 | INVALID_IMEI_PROVIDED | Invalid IMEI provided |
| 400 | SERVICE_ID_MUST_BE_NUMBER | Service ID must be a number |
| 400 | BATCH_NAME_REQUIRED | Batch name is required |
| 400 | IMEI_REQUIRED | IMEI is required |
| 403 | CREDIT_LIMIT_REACHED | Credit limit reached |
| 403 | LOW_CREDIT | Low credit |
| 404 | SERVICE_NOT_FOUND | Service not found |
| 405 | SERVICE_IS_DISABLED | Service is disabled |
GET /order/single — Get Single Order
| HTTP | Code | Meaning |
|---|---|---|
| 400 | INVALID_ORDER_ID | Invalid order ID |
| 404 | ORDER_NOT_FOUND | Order not found |
GET /batch — List Batches
| HTTP | Code | Meaning |
|---|---|---|
| 400 | INVALID_PAGE_NUMBER | Invalid page number |
| 400 | PAGE_NUMBER_INVALID | Page number is invalid |
| 400 | INVALID_PAGE_SIZE | Page size cannot exceed 5000 |
| 400 | PAGE_SIZE_INVALID | Page size is invalid |
| 400 | MIN_PAGE_SIZE | Page size minimum is 5 |
| 400 | BATCH_STATUS_INVALID | Batch status not valid |
| 400 | SERVICE_ID_INVALID | Service ID not valid |
| 400 | SUBUSERS_MUST_BE_LIST | Subusers must be a list |
| 400 | SUBUSERS_ARE_INVALID | Subusers are invalid |
| 400 | SEARCH_VALUE_IS_INVALID | Search value is invalid |
| 400 | INVALID_BATCH_ID_PROVIDED | Invalid batch ID provided |
| 400 | FROM_DATE_REQUIRED | From date is required |
| 400 | INVALID_DATE_PROVIDED | Invalid date provided |
| 400 | TO_DATE_REQUIRED | To date is required |
| 400 | INVALID_SORT_VALUE | Invalid sort value |
GET /service — List Services
| HTTP | Code | Meaning |
|---|---|---|
| 400 | PAGE_NUMBER_INVALID | Page number is invalid |
| 400 | PAGE_NUMBER_REQUIRED | Page number is required |
| 400 | PAGE_SIZE_REQUIRED | Page size is required |
| 400 | PAGE_SIZE_INVALID | Page size is invalid |
| 400 | FILTER_VALUE_INVALID | Filter value is invalid |
Authentication
- API Key: api-key
Most REST endpoints expect your API key in the access-key header. GET /order/browser is the one exception and takes the key in the key query parameter. The IP allow-list applies to all REST endpoints, including GET /order/browser. Add your server's IP address to the allow-list in the dashboard. See the Authentication guide.
Security Scheme Type: | apiKey |
|---|---|
Header parameter name: | access-key |