> This page is for Developers. > For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.emnify.com/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.emnify.com/_mcp/server. > Handle API errors with comprehensive JSON error codes, tokens, and messages including validation, authentication, and resource-specific errors. The API returns HTTP error codes according to the type of the error: * `400` error codes are used for client related issues * `500` error codes indicate server side issues ## JSON error representation `403` status codes are returned with the following JSON error: ```json { "error_code" : 1104, "error_token": "Forbidden", "message": "You do not have the necessary permissions to access this entry point. Please contact your administrator." } ``` `400` error codes come with a consumable JSON error representation: ```json { "error_code" : 1406, "error_token" : "NotAllowed", "message" : "Updating of own organisation not allowed.", } ``` Some error codes like `ValidationFailed` can contain multiple error messages embedded: ```json {4, 9, 14} { "error_code" : 1400, "error_token" : "InputValidationFailed", "message" : "Input validation failed", "errors" : [ { "error_code" : 1403, "error_token" : "InvalidFormat", "message" : "User - Username has invalid format: expecting String." }, { "error_code" : 1402, "error_token" : "Required", "message" : "User - organisation is required." } ] } ``` ## Permission errors The API returns `403 Forbidden` with the `Forbidden` error token when your user's role doesn't include the permission that the endpoint requires. A `403` can also mean the feature isn't enabled for your organization, which is separate from your role. To resolve a `403` error, ask an administrator of your organization to grant you a role that includes the permission the endpoint requires. To see which permission and roles an endpoint needs, check the *Required permissions* callout at the top of its reference page. You can [assign roles through the API](/developers/api-guidelines/manage-permissions), and [Permissions](/developers/api-guidelines/permissions) covers how permissions work and which permissions each system role includes. ## List of error codes ### Generic error codes There are several error categories that have general applicability within API and aren't specific to any particular resource. | Category | HTTP Status | Error Code | Error Token | Description and parameters | | :------------- | :----------- | :---------- | :-------------------- | :------------------------------------------------------------------------- | | Authentication | 401 | 1101 | InvalidCredentials | | | Authentication | 401 | 1102 | InvalidToken | | | Authentication | 401 | 1103 | TokenExpired | | | Authentication | 403 | 1104 | Forbidden | Role lacks the required permission | | Authentication | 429 | 1105 | TooManyRequests | | | Navigation | 404 | 1201 | NotFound | \{resource} with id \{id} not found | | Paging | 422 | 1301 | InvalidQueryCriteria | Search criteria \{criteria} is invalid | | Paging | 422 | 1302 | InvalidSortCriteria | Sort criteria \{criteria} is invalid | | Validation | 422 | 1400 | InputValidationFailed | | | Validation | 422 | 1401 | InvalidReference | Invalid reference to \{resource} with id \{id} | | Validation | 422 | 1402 | Required | \{Object} - \{field} is required | | Validation | 422 | 1403 | InvalidFormat | \{Object} - \{field} has invalid format: Expecting \{String/Number/Object} | | Validation | 422 | 1404 | OutOfRange | \{Object} - \{field} out of range (\{range}) | | Validation | 409 | 1405 | Duplicated | \{Object} - \{field} already exists | | Validation | 400 | 1406 | NotAllowed | \{Action} not allowed | | Validation | 409 | 1407 | CannotBeDeleted | \{Object} still referenced | | Validation | 422 | 1408 | InvalidValue | \{Object} - \{field} is invalid: \{value} | | Validation | 422 | 1409 | UnknownProperty | Unknown Property: \{property} | | Validation | 422 | 1410 | InvalidJson | Invalid request: \{reason} | | Rate Limit | 429 | 1501 | TooManyRequests | Too many requests | | Unavailable | 404 | 1601 | Unavailable | No \{resource} available | | Connectivity | 404 | 1901 | UnknownSubscriber | Unknown Subscriber for Endpoint with id \{id}\* | | Connectivity | 404 | 1904 | UnknownLocation | Unknown Location for Endpoint with id \{id}\* | ### Connectivity errors This section provides additional information about endpoint connectivity errors with HTTP `404` status codes are returned. **Unknown Subscriber Error**\ This error indicates that the subscriber isn't registered in the HLR. This can occur if the IMSI doesn't belong to emnify, the IMSI isn't assigned to any SIM, the SIM isn't activated or is suspended, etc. **Unknown Location Error**\ This error is used when the service request is made for a subscriber without valid location data (that is, no location information is present in the HLR; this can occur if the IMSI is detached or didn't respond to paging). **External Network Error**\ This error is used when the source of the error is external to the system, for example, timeout on a Network Request towards VPLMN. **Network Element Not Available Error**\ This error indicates no network element available to process the service request. **Data Missing**\ An example of missing data would be a missing optional parameter required by the context. **Unexpected Data Value**\ Invalid data, for example, an invalid MSISDN or IMSI. ### Resource-specific errors Errors that are specific to a particular resource and operation being performed are described in resource section. Most of the errors in this category return `409 Conflict` HTTP status code. For example, trying to activate an endpoint that has no SIM card associated causes the following error: ```http 409 Conflict ``` ```json { "error_code" : 2101, "error_token" : "UnableToActivate", "message" : "Unable to activate", "description" : "No SIM." } ``` Resource specific errors are segmented as follows: | Code range | Resource | | :--------- | :--------------- | | 2100-2199 | Endpoint | | 2200-2299 | SIM | | 2300-2399 | Service profiles | | 2400-2499 | Traffic limits | | 2500-2599 | User | | 2600-2699 | Tariff | | 2700-2799 | IP Address Space | > **Warning** > > **Warning**: > Responses with different root causes may share an error code and token. > Be sure to check the error message to determine the exact cause. > > For example, the [Create IP address space](/developers/api/ip-address-spaces/ip-address-space-post) call has two possible reasons for returning a `422`: > The requested IP address space isn't allowed or overlaps with a reserved range. > These scenarios are both considered out of range, so each response contains an `OutOfRange` error token and `2701` error code. > The `message` indicates the cause of the error.