Error codes

Last updated June 26th, 2024

The Knox MSP Portal API uses conventional HTTP response codes to indicate the success or failure of a request. A 2XX response code indicates success, a 4XX response code indicates a client-side error due to the request inputs, and a 5XX response code indicates a server-side error. There are also custom error codes specific to the Knox MSP Portal API listed below.

Error object

Each error response contains a JSON body with additional information about the error. The error objects contain the following attributes:

Attribute	Type	Description
`transactionalId`	String	A string used to identify the exact transaction that returned the error object.
`code`	String	The name of the error code.
`errorCode`	String	The error code number. If it’s unique to the Knox MSP Portal, it’s a more specific indicator of the error than the HTTP response code.
`errorMessage`	String	A description of the error, intended to help developers debug the error response.

Following is an example 403 response:

HTTP/1.1 403 Unauthorized

Content-Type: application/json

{
    "transactionalId": "6m789un9-982d-12u6-7899-n9wre821m26m",
    "code": "AUTHORIZATION_FAIL",
    "errorCode": "4030000",
    "errorMessage": "The current user is unauthorized to use this service."
}

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 (for instance, check validation errors in your request payload).
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 cannot 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 MSP Portal error codes

The Knox MSP Portal API uses custom error codes which provide more information than the standard HTTP error response codes. The following table lists the Knox MSP Portal API error codes and their descriptions:

Code	Name	Description
5000000	FAILURE	Internal Server Error.
4030000	AUTHORIZATION_FAIL	The current user is unauthorized to use this service.
4002108	INVALID_COUNTRY	Unsupported country.
4002100	ADD_EC_CUSTOMER_INVALID	This customer doesn’t exist or the ID isn’t a valid customer ID.
4002101	ADD_EC_CUSTOMER_NOT_APPROVED	This customer is currently either pending approval or has been rejected by the Samsung administrator.
4002102	ADD_EC_DELINK_PENDING	This customer is currently in the process of being delinked from an MSP and cannot be added until this process is complete.
4002103	ADD_EC_ALREADY_MANAGED	This customer is already managed by someone else.
4002104	ADD_EC_PENDING_CANNOT_ADD_AGAIN	This customer is ‘Pending’ and cannot be added again.
4002105	ADD_EC_NOT_SAME_REGION	This customer is not available in your region.
4042100	CUSTOMER_NOT_FOUND	This customer doesn’t exist.
4002113	CUSTOMER_NOT_MANAGED_BY_MSP	Customer not managed by the current MSP.
4002106	EMAIL_ALREADY_IN_USAGE	Knox cloud services account already exists for this user. Please contact the customer or Samsung administrator.
4002109	SERVICE_NOT_VALID_SCP	The Knox MSP Portal API does not support Samsung Care Plus.
4002112	CANNOT_DELINK_FULLY_MANAGED	Cannot delink a fully managed customer.
4002115	CUSTOMER_PENDING_CANNOT_DELINK	Customer is in pending state, cannot be delinked.
4002111	KM_TENANT_PREFIX_INVALID	Prefix can’t begin or end with a period.
4002110	KM_DOMAIN_NAME_ALREADY_EXISTS	Prefix is required because the domain name already exists.
4002114	BLOCKED_DOMAIN_FOR_JOINTLY_MANAGED	This email domain is not allowed for jointly managed customers.
4002116	CANNOT_CHANGE_WHEN_DELINKING	Customer cannot be changed while delink request is pending.
4002117	CANNOT_UPDATE_FROM_JOINTLY_TO_FULLY	Can’t update from jointly managed to fully managed.
4002118	SERVICE_NOT_ASSOCIATED_TO_CUSTOMER_ACCOUNT	Service not associated with this customer’s account.
4002119	CANNOT_CHANGE_WHEN_PENDING	Customer can’t be changed while in pending to link status.
4002120	ACCESS_TYPE_REQUIRED	`Access type` param is required when adding new services.
4002121	KM_DOMAIN_NAME_ALREADY_IN_USAGE	The organization domain is already in use. Please add a prefix to uniquely identify your organization or to manage multiple Knox Manage administrator accounts under the same organization.
4002124	MSP_CANNOT_MANAGE_KG	This MSP doesn’t manage Knox Guard, please remove Knox Guard from the managed services list.

Troubleshooting

If your request returns a 400 level error

Find the specific error code in the table above and refer to the error message for details.

If your request returns a 500 level error

Please try the request again at a later time.