Back to top

Error codes

Last updated June 13th, 2024

The Knox E-FOTA API uses the conventional HTTP response code to indicate the success or failure of a request. A 2XX response code indicates success, a 4XX response code indicates an error given the inputs of the request, and a 5XX response code indicates a failure with the Knox E-FOTA platform.

Standard HTTP error codes

The following table lists the most common HTTP error responses:

Code Name Description
200 Success The request was successfully received.
400 Bad request The client has issued an invalid request. Verify your request (ex. check validation errors in your request load).
401 Unauthorized Authorization for the API is required, but the request has not been authenticated.
403 Forbidden The request has been authenticated but does not have the appropriate permissions, or the requested resource not be found.
404 Not found The requested path or the specified user does not exist.
409 Conflict The request could not be completed due to a conflict with the current state of the target resource.
500 Server error An error has occurred on the server. Please try again later.

Knox E-FOTA error codes

Knox E-FOTA specifies custom error codes for each endpoint. The custom error codes are returned under HTTP error code 400, while WRONG_ACCESS errors are returned under HTTP error code 403.

Campaign error codes

Create campaign

Code Message errorKey errorMessage Description
00006 INTERNAL_SERVER_ERROR We couldn't create the campaign due to a server error. Please try again later. Error with Knox E-FOTA servers.
03001 CAMPAIGN_NAME_DUPLICATE_FOUND name This campaign name already exists—choose another one. Campaign name already exists, pick another campaign name.
03002 CAMPAIGN_INVALID_REQUEST_DATA name Enter a campaign name. Campaign name must be defined for campaign creation.
startDate Choose a start date for the campaign. startDate parameter must be defined.
startDate Make sure the campaign starts either today or on a future date. startDate parameter must be set to today or a future day.
startDate Make sure the campaign's start date is valid. startDate parameter is invalid.
endDate Make sure the campaign's end date is valid. endDate parameter is invalid.
endDate Make sure the campaign's end date is after its start date. endDate must be after startDate.
endDate Make sure the campaign's end date is either today or on a future date. endDate parameter must be set to today or a future day.
timezone Choose a time zone for the campaign. timezone parameter must be defined.
timezone Make sure the campaign's time zone is valid. timezone parameter entered is invalid.
from Choose a time to begin installing the firmware Firmware install from time must be defined so installation window starts at the given time.
from Make sure the firmware installation start time is valid. Firmware install from time must be valid so firmware installation window starts at a valid time.
to Choose a time for the firmware to finish installing by. Firmware install to time must be defined so installation window ends at the given time.
to Make sure the time for the firmware to finish installing by is valid. Firmware install to time must be valid so installation window ends at a valid time.
to Make sure there are at least 3 hours between when the firmware starts and finishes installing. The time window between firmware install from and to must be at least 3 hours to allow firmware to install.
downloadTime Choose a time for the firmware to start downloading at. Campaign download time must be defined so firmware downloads can take place.
downloadTime Make sure the time for the firmware to start downloading at is valid. Campaign download time must be valid so firmware download can take place.
postponeInstallation Make sure you enter the number of times the device user can postpone installation or leave it empty. Campaign postpone installation time should be valid or left empty for a default value of zero.
postponeDuration You can only set a length of time to postpone the reminder if the device user can postpone installation. If postponeInstallation is set to zero then postponeDuration must also be zero to indicate that the firmware installation can't be postponed.
autoInstallTime You can only set a length of time for the firmware to automatically start installing afterward if the device user can postpone installation. If postponeInstallation is set to zero then autoInstallTime must also be zero to indicate that firmware will instantly automatically install.
downloadNetwork Choose the networks you want the firmware to be downloaded through. downloadNetwork must be defined so firmware can be downloaded with the desired networks.
downloadNetwork Make sure the network types you selected are valid. downloadNetwork must be valid so firmware can be downloaded with the desired networks.
downloadAvailable
DuringRoamingNetwork
You can only allow downloads when roaming if firmware can be downloaded on a mobile network. If downloadNetwork does not allow mobile network then download using roaming must be false.
switchtoWifi You can only set whether to switch downloads to Wi-Fi if firmware can also be downloaded on a mobile network. switchtoWifi must be zero if downloadNetwork is set to WIFIONLY.
downloadSpeed Make sure the download speed you entered is valid. Download speed limit entered is invalid.
batteryLevel Make sure you entered a minimum battery level between 20% and 80%. Minimum battery level allowed for installation should be between 20% and 80%.
emailAddress Enter an email address to be used as contact information. Campaign email address must be defined so it can be used as contact information
emailAddress Invalid email address. Campaign email address must be valid so it can be used as contact information
phoneNumber Enter a phone number to be used as contact information. Campaign phone number must be defined so it can be used as contact information
phoneNumber Invalid phone number. Campaign phone number must be valid so it can be used as contact information
gradualRolloutNumber Make sure you enable gradual rollout first. Gradual rollout must be enabled before you can set gradual rollout percentage.
gradualRolloutNumber Make sure you entered a percentage between 1 and 50%. Gradual rollout number must be between 1% and 50%.
ssidThrottling
.ssidForThrottling
Make sure you entered a valid SSID. Make sure you've entered valid SSIDs to throttle download speeds over these networks.
ssidThrottling
.ssidForThrottling
Make sure the SSID is under 50 characters. Make sure the SSIDs you've entered are under 50 characters.
ssidThrottling
.maxSpeedThrottling
Make sure the maximum download speed is a possible value. Make sure you've entered a valid maximum download speed.
allowOrBlock You can only use 0, 1, or 2 for these values. allowOrBlock can only be either 0, 1, or 2. Where 0 means allowOrBlock is disabled, 1 means it's an allowlist, and 2 means it's a blocklist.
allowOrBlock Make sure the values for allow or block is equal to 1 or 2. allowOrBlock must be 1 or 2 if you're also using the ssidsForRestriction field.
ssidsForRestriction
.ssidForRestriction
Make sure you entered a valid SSID. Make sure you've entered valid SSIDs to restrict firmware downloads for these networks.
ssidsForRestriction
.ssidForRestriction
Make sure the SSID is under 50 characters. Make sure the SSIDs you've entered are under 50 characters.
ssidsForRestriction
.descriptionRestriction
Make sure the description is under 500 characters. Make sure the network description you've entered is under 500 characters.

Delete campaign

Code Message errorKey errorMessage Description
03002 CAMPAIGN_INVALID_REQUEST_DATA campaignId Make sure you entered the correct campaign ID. Make sure you've entered the correct campaignId
campaignId Make sure no EMM devices or groups are assigned to this campaign before you delete it. This campaign can't be deleted because an EMM device or EMM group is assigned to this campaign.
campaignId We couldn't delete this campaign because it's set to be assigned to new devices uploaded by a reseller. Check your reseller preferences. This campaign can't be deleted because it is being used by a reseller's autoSync.
4030001 WRONG_ACCESS No entry found Check that you have provided a campaign ID, that there are no typos in the endpoint, and that the correct HTTP method is used.

Cancel campaign

Code Message errorKey errorMessage Description
00001 RESOURCE_INVALID_PARAM We couldn't find any account information. Tenant information must be provided.
03002 CAMPAIGN_INVALID_REQUEST_DATA campaignId Make sure you entered the correct campaign ID. Make sure you've entered the correct campaign ID.
4030001 WRONG_ACCESS No entry found Check that you have provided a campaign ID, that there are no typos in the endpoint, and that the correct HTTP method is used.

Get campaign

Code Message errorKey errorMessage Description
03002 CAMPAIGN_INVALID_REQUEST_DATA We couldn't find any account information. Make sure you've entered a campaign ID.
03003 CAMPAIGN_NOT_FOUND campaignId Make sure you entered the correct campaign ID. Make sure you've entered the correct campaign ID.

List campaign

Code Message errorMessage Description
00001 RESOURCE_INVALID_PARAM We couldn't find any campaigns. Campaigns could not be found.
The lowest page number you can enter is 0. Enter a valid page number greater than or equal to 0.
Make sure you're displaying at least 1 entry per page. Enter a valid page size greater than or equal to 1.
Make sure you're displaying less than 100 entries per page. Enter a valid page size less than or equal to 100.
You can only sort by start date, end date, modified date, device count, or campaign name. Sort by must be one of the following values: status, startDate, endDate, modified, deviceCount, or campaignName.
You can only sort in either ascending or descending order. Sort order must be either ASC for ascending order, or DESC for descending order.
A campaign's status can only be active, scheduled, cancelled, or expired. Status must be one of the following values: Scheduled, Active, Cancelled, or Expired.
You need to enter a valid Unix timestamp to search for campaigns from a specific date. modifiedTimeFrom must be a Unix timestamp greater than or equal to 0.
You need to enter a valid Unix timestamp to search for campaigns from a specific date. modifiedTimeFrom must be a Unix timestamp greater than or equal to 0.
03002 CAMPAIGN_INVALID_REQUEST_DATA We couldn't find any account information. Tenant information could not be found.
Enter a search query, like a campaign name. Search parameter is empty.

Update campaign

Code Message errorKey errorMessage Description
03001 CAMPAIGN_NAME_DUPLICATE_FOUND name This campaign name already exists—choose another one. Campaign name already exists, pick another campaign name.
03002 CAMPAIGN_INVALID_REQUEST_DATA name Make sure you entered the correct campaign ID. Campaign name must be defined for campaign creation.
startDate Choose a start date for the campaign. startDate parameter must be defined.
startDate Make sure the campaign starts either today or on a future date. startDate parameter must be set to today or a future day.
startDate Make sure the campaign's start date is valid. startDate parameter is invalid.
endDate Make sure the campaign's end date is valid. endDate parameter is invalid.
endDate Make sure the campaign's end date is after its start date. endDate must be after startDate.
endDate Make sure the campaign starts either today or on a future date. endDate parameter must be set to today or a future day.
timezone Choose a time zone for the campaign. timezone parameter must be defined.
timezone Make sure the campaign's time zone is valid. timezone parameter entered is invalid.
from Choose a time to begin installing the firmware. Firmware install from time must be defined so install can start at the given time.
from Make sure the firmware installation start time is valid. Firmware install from time must be valid so firmware can install at a valid time.
to Choose a time to finish installing the firmware by. Firmware install to time must be defined so install can end at the given time.
to Make sure the firmware installation end time is valid. Firmware install to time must be valid so install can end at a valid time.
to Make sure there are at least 3 hours between when the firmware starts and finishes installing. The gap between firmware install from time and to time must be more than 3 hours to allow firmware to install.
downloadTime Choose a time for the firmware to start downloading. Campaign download time must be defined so firmware download can start at the given time.
downloadTime Make sure the start time for the firmware download is valid. Campaign download time must be valid so firmware download can start.
postponeInstallation Make sure you enter the number of times the device user can postpone installation or leave it empty. Campaign postpone installation time should be valid or left empty for default value of 0.
postponeDuration You can only postpone reminders if the device user is allowed to postpone installation. If postponeInstallation is set to zero then postponeDuration must also be zero to indicate that the firmware installation can't be postponed.
autoInstallTime You can automatically install firmware only if the device user is allowed to postpone installation. If postponeInstallation is set to zero then autoInstallTime should also be zero to indicate that firmware will instantly automatically install.
downloadNetwork Choose the networks you want the firmware to be downloaded through. downloadNetwork must be defined so firmware can be downloaded with the desired networks.
downloadNetwork Make sure the network types you selected are valid. downloadNetwork must be valid so firmware can be downloaded with the desired networks.
downloadAvailable
DuringRoamingNetwork
You can allow downloads when roaming only if firmware can also be downloaded on a mobile network. If downloadNetwork does not allow mobile network then download using roaming must be false.
switchtoWifi You can set whether to switch downloads to Wi-Fi only if firmware can also be downloaded on a mobile network. switchtoWifi must be zero if downloadNetwork is set to WIFIONLY.
downloadSpeed Make sure the download speed limit you entered is valid. Download speed limit entered is invalid.
batteryLevel Make sure you entered a minimum battery level between 20% and 80%. Minimum battery level allowed for installation should be between 20% and 80%.
emailAddress Enter an email address to be used as contact information. Campaign email address must be defined so it can be used as contact information.
emailAddress Invalid email address. Campaign email address must be valid so it can be used as contact information
phoneNumber Enter a phone number to be used as contact information. Campaign phone number must be defined so it can be used as contact information.
phoneNumber Invalid phone number. Campaign phone number must be valid so it can be used as contact information
gradualRolloutNumber Make sure you enable gradual rollout first. Gradual rollout must be enabled before you can set gradual rollout percentage.
gradualRolloutNumber Make sure you entered a percentage between 1 and 50%. Gradual rollout number must be between 1% and 50%.
ssidThrottling
.ssidForThrottling
Make sure you entered a valid SSID. Make sure you've entered valid SSIDs to throttle download speeds over these networks.
ssidThrottling
.ssidForThrottling
Make sure the SSID is under 50 characters. Make sure the SSIDs you've entered are under 50 characters.
ssidThrottling
.maxSpeedThrottling
Make sure the maximum download speed is a possible value. Make sure you've entered a valid maximum download speed.
allowOrBlock You can only use 0, 1, or 2 for these values. allowOrBlock can only be either 0, 1, or 2. Where 0 means allowOrBlock is disabled, 1 means it's an allowlist, and 2 means it's a blocklist.
allowOrBlock Make sure the values for allow or block is equal to 1 or 2. allowOrBlock must be 1 or 2 if you're also using the ssidsForRestriction field.
ssidsForRestriction
.ssidForRestriction
Make sure you entered a valid SSID. Make sure you've entered valid SSIDs to restrict firmware downloads for these networks.
ssidsForRestriction
.ssidForRestriction
Make sure the SSID is under 50 characters. Make sure the SSIDs you've entered are under 50 characters.
ssidsForRestriction .descriptionRestriction Make sure the description is under 500 characters. Make sure the network description you've entered is under 500 characters.
03003 CAMPAIGN_NOT_FOUND campaignId Make sure you entered the correct campaign ID. Make sure you've entered the correct campaign ID.
4030001 WRONG_ACCESS No entry found Check that you have provided a campaign ID, that there are no typos in the endpoint, and that the correct HTTP method is used.

Assign error codes

Assign campaign

Code Message errorMessage Description
00001 RESOURCE_INVALID_PARAM

You need to provide a request body.

Make sure you're adding a valid device ID.

You can only assign up to 1,000 devices per campaign.

deviceIds parameter is either missing or invalid. Check the parameter in your request according to the error message.
00005 RESOURCE_CONFLICT Make sure you're entering the right campaign ID and that the devices you're assigning are in your account. Resource conflict has occurred. Check that you've entered your campaign ID properly, and ensure that the devices you're assigning are in your account.
02001 DEVICE_NOT_FOUND Make sure you're entering the right device IMEIs or serial numbers. Device could not be found. Check that your device IMEIs/Serial numbers are entered properly.
4030001 WRONG_ACCESS No entry found Check that you have provided a campaign ID, that there are no typos in the endpoint, and that the correct HTTP method is used.

Unassign campaign

Code Message errorMessage Description
00001 RESOURCE_INVALID_PARAM

You need to provide a request body.

Make sure you're adding a valid device ID.

You can only unassign up to 1,000 devices per campaign.

deviceIds parameter is either missing or invalid. Check the parameter in your request according to the error message.
00005 RESOURCE_CONFLICT Make sure you're entering the right campaign ID and that the devices you're unassigning are in your account. Resource conflict has occurred. Check that you've entered your campaign ID properly, and ensure that the devices you're assigning are in your account.
02001 DEVICE_NOT_FOUND Make sure you're entering the right device IMEIs or serial numbers. No device was found. Check that your device IMEIs/Serial numbers are entered properly.
02003 DEVICE_STATUS_NOT_VALID Make sure you're entering the right device IMEIs or serial numbers and they're assigned to a campaign. Device is not in a valid status to be unassigned. Check that the device IMEI/Serial numbers are correct and that they are assigned to a campaign.
4030001 WRONG_ACCESS No entry found Check that you have provided a campaign ID, that there are no typos in the endpoint, and that the correct HTTP method is used.

Firmware Policy error codes

Get Firmware Policy

Code Message errorMessage Description
03003 CAMPAIGN_NOT_FOUND Campaign not found Make sure a campaign ID is included in the request.

Update Firmware Policy

Code Message errorMessage Description
00001 RESOURCE_INVALID_PARAM

firmwares must not be null

firmwares[n].model must not be blank

firmwares[n].isManual must not be null

firmwares[n].salesCode must not be blank

*n is the index of firmwareList

Invalid parameter(s) in the request. Check your parameters in your request according to the error message.
03002 CAMPAIGN_INVALID_REQUEST_DATA Campaign name is not defined Make sure a campaign ID is included in the request.

Device error codes

Upload devices

Code Message errorMessage Description
00001 RESOURCE_INVALID_PARAM

imeiOrSns must not be empty

Invalid parameter(s) in the request. Check your parameters in your request according to the error message.
02016 DEVICE_LIST_OVER_MAX_SIZE DEVICE_LIST_OVER_MAX_SIZE List of devices exceeds maximum size of 10,000.

Delete devices

Code Message errorMessage Description
00001 RESOURCE_INVALID_PARAM

imeiOrSns must not be empty

Invalid parameter(s) in the request. Check your parameters in your request according to the error message.
02016 DEVICE_LIST_OVER_MAX_SIZE DEVICE_LIST_OVER_MAX_SIZE List of devices exceeds maximum size of 10,000.

List devices

Code Message errorMessage Description
00001 RESOURCE_INVALID_PARAM

pageNum must be greater than or equal to 0

pageSize must be greater than or equal to 1

pageSize must be less than or equal to 100

Invalid parameter(s) in the request. Check your parameters in your request according to the error message.

Get models

Code Message errorMessage Description
4030001 WRONG_ACCESS

No entry found

Invalid parameter(s) in the request. Check your parameters in your request according to the error message.

Get carrier codes

Code Message errorMessage Description
4030001 WRONG_ACCESS

No entry found

Invalid parameter(s) in the request. Check your parameters in your request according to the error message.

Get device details

Code Message errorMessage Description
02001 DEVICE_NOT_FOUND

DEVICE_NOT_FOUND

Device could not be found

Get status count

Code Message errorMessage Description
4030001 WRONG_ACCESS

No entry found

No entries found

Force client refresh

Code Message errorMessage Description
00001 RESOURCE_INVALID_PARAM

deviceIds must not be empty

deviceIds must be greater than or equal to 1

deviceIds must be less than or equal to 1000

Invalid parameter(s) in the request. Check your parameters in your request according to the error message.

Get model CSC

Code Message errorMessage Description
00001 RESOURCE_INVALID_PARAM

Parameter should not be null

Required String parameter 'model' is not present

Required String parameter 'carrierCode' is not present

Invalid parameter(s) in the request. Check your parameters in your request according to the error message.

License error codes

Get license list

Code Message errorMessage Description
4032251 ACCESS_TOKEN_EXPIRED ACCESS_TOKEN_EXPIRED Your access token has expired, you must create a new one to continue making requests.
00001 RESOURCE_INVALID_PARAM

sortBy must match status|startDate|endDate|modified|deviceCount|achievedRate

sortBy parameter only accepts these inputs: status, startDate, endDate, modified, deviceCount, archievedRate.

Register license

Code Message errorMessage Description
00001 RESOURCE_INVALID_PARAM

licenseName must not be empty

licenseKey must not be empty

Required request body is missing

Invalid parameter(s) in the request. Check your parameters in your request according to the error message.
18004 LICENSE_NOT_ACTIVE The state of the license to register is Terminated. The license you are trying to register has been terminated.
18003 LICENSE_ALREADY_EXPIRED The state of the license to register is Expired. The license you are trying to register is expired.
18023 LICENSE_NAME_ALREADY_EXISTS Duplicate license name already exists. A license with this name already exists, please pick a different license name.
18012 LICENSE_INVALID Failed to validate the license key. Please check the license key. The provided license key is invalid. Please check your license key.
18010 LICENSE_FAILED_TO_REGISTER Failed to register license. This license could not be registered. Please use a different license key.
18026 LICENSE_KEY_ALREADY_EXISTS_IN_OTHER_REGION The license key already exists in the other region. This license key already exists in another region. Please use a different license key.
18027 LICENSE_KEY_ALREADY_USED The license key is already used. This license key has already been registered.
08002 TENANT_NOT_FOUND Tenant not found. Tenant for this license could not be found.
00006 INTERNAL_SERVER_ERROR INTERNAL_SERVER_ERROR The server has encountered an internal error. Please try again later.

Generate trial license

Code Message errorMessage Description
00001 RESOURCE_INVALID_PARAM Required LicenseType parameter 'licenseType' is not present Invalid parameter(s) in the request. Check your parameters in your request according to the error message.
00006 INTERNAL_SERVER_ERROR INTERNAL_SERVER_ERROR The server has encountered an internal error. Please try again later.
18002 LICENSE_LMS_INTERNAL_ERROR Generating trial license failed Trial license generation failed. Please try again later.
18024 LICENSE_INVALID_TYPE Received invalid trial license type request Invalid license type. Please check the licenseType parameter.
18009 LICENSE_MAX_KFM_TRIAL_LICENSE_COUNT_REACHED Trial License already exists. A trial license already exists. You can only have 1 trial license at a time.

Delete license

Code Message errorMessage Description
00001 RESOURCE_INVALID_PARAM This license is assigned to device(s) Invalid parameter(s) in the request. This license is already assigned to devices.
00006 INTERNAL_SERVER_ERROR INTERNAL_SERVER_ERROR The server has encountered an internal error. Please try again later.
18002 LICENSE_LMS_INTERNAL_ERROR Generating trial license failed Internal error occurred when deleting license. Please try again later.
18006 LICENSE_FAILED_DELETE_LICENSE LICENSE_FAILED_DELETE_LICENSE License deletion failed. Please try again later.
18016 LICENSE_DOES_NOT_EXIST Requested licenseId does not exist. This license could not be found, please check the licenseId parameter and ensure that this license exists.

FOTA error codes

Get firmware list

Code Message errorMessage Description
00001 RESOURCE_INVALID_PARAM

modelName must not be blank

carrierCode must not be blank

csc must not be blank

status must not be null

openedDate pattern is invalid

Invalid parameter(s) in the request. Check your parameters in your request according to the error message.

Troubleshooting

If your request returns a 400 level error

Check the specific error code and refer to the error codes section of this reference.

If your request returns a 500 level error

Please try the request again at a later time.

Limits and quotas on API requests

API call limits have been implemented to maintain stable service operations.

For each IP

Each customer will be able to call the API up to 25 times every second with the same IP address. If your cloud system is using a public IP when calling the Knox E-FOTA API, please ensure that your API calls do not surpass the limit.

For each user

The super admin of each tenant will receive tokens through Knox Cloud API key generation. Once the API key is generated, all users under this tenant will be able to call the Knox E-FOTA API using the token. Each admin under the same tenant will be able to make API requests at a maximum of 25 calls every second.

For each API key

The API token can be used up to a maximum of 25 API calls every second.

Is this page helpful?