API Errors

When an error is received, a status is returned and the response is signed as with any other response. Error responses should be validated to ensure their integrity.

400 Bad Request

HTTP status 400 Bad Request is the most common error returned when an HTTP request to the API provided valid credentials and had permissions to perform the requested action. These errors can include JWT validation errors, data validation errors, or invalid state errors. This response contains encrypted data just as a non-error response would. The decrypted response JSON contains the following elements:

error_code:

string The Error Code triggered.

error_detail:

string|object Details of the error condition. This may be a singular error message or an object with of multiple errors incurred while processing the request. Please refer to the Error Codes section to determine the detail type.

Warning

As the message is encrypted, it may contain private information that should not be passed along to the user.

Example HTTP Message:

HTTP/1.1 400 Bad Request
X-IOV-JWT: eyJhbGciOiJSU0EtT0FFUCIsIm.VuYyI6IkEyNTZHQ00ifQ.OKOawDo13gRp2ojaHV7LF
Content-Type: application/jose; charset=UTF-8
Content-Length: 139

eyJhbGciOiAiUlNBLU9BRVAiLCAiZW5jIjogIkEyNTZ.Ppd6dIAkGwcfIelfqOrj3rkw.71lYoW6jBJymhM-QLBQAWA.t-4rRH6GsoXt0.1DGC4k

Example Decrypted Body for Detail String:

{"error_code": "KEY-005", "error_detail": "The key cannot be deleted as no other key exists."}

Example Decrypted Body for Detail Object:

{"error_code": "ARG-002", "error_detail": {"policy": "Invalid Policy supplied"}}

Error Codes

ARG-001:Data validation error. The error_detail includes a hierarchical key/value structure matching the request data structure with the key being the data element that did not pass validation and the value being the validation failure reason.
ARG-002:Internal use only.
DIR-001:The directory identifier supplied is not valid. This can occur when attempting to perform an operation involving a Directory User and the identifier supplied in the request was not valid.
DIR-002:No longer in use.
DIR-003:No longer in use.
DIR-004:The directory ID provided either does not exist or is not accessible. This occurs when trying to modify a child element of a Directory identified by ID within the request.
DIR-005:Internal use only.
KEY-001:The public key supplied is not valid. When attempting to add a Public Key to an entity, the Pubic Key provided is not a valid RSA Public Key.
KEY-002:The public key supplied already exists. It cannot be added again. This occurs when attempting to add a Public Key to an entity but the Public Key was previously added.
KEY-003:The key_id supplied could not be found. This occurs when attempting to update an existing Public Key for an entity but the ID provided is not associated with a Public Key that currently exists for the entity.
KEY-004:The key cannot be deleted as no other key exists. This occurs when you attempt to remove a Private Key from an entity for which only one Public Key exists. This would leave the entity in an unusable state.
ORG-001:Internal use only.
ORG-002:Internal use only.
ORG-003:Directory name already in use. When creating or updating a Directory, the name is already in use by another Directory in the Organization.
ORG-004:Internal use only.
ORG-005:Only one SDK Key exists for the Directory. This occurs when attempting to remove an SDK Key from a Directory for which only one SDK Key exists. This would leave the Directory in an unusable state.
ORG-006:The supplied SDK key is not associated with the subject Directory. This occurs when attempting to remove an SDK Key from a Directory that does not contain the SDK Key in question.
SVC-001:When attempting to add or rename a Service, the name requested was already in use.
SVC-002:During an authentication request, the policy provided for the call was not valid.
SVC-003:Policy Check Failure. The Policy requirements were not met. This would either be related failing time fence restrictions or none of the User’s Devices passed the required jail break protection.
SVC-004:This is an attempt to modify or delete a Service entity or Service entity child Entity for a non-existent Service.
SVC-005:An authentication request already exists. Another one cannot be created until it has been responded to or expires.
SVC-006:Authentication request has a response and cannot be modified.
SVC-007:Authentication request has been canceled.

Hint

Error codes marked as Internal use only are returned from calls not available externally. Error codes marked as No longer in use are retired. From time to time, an error code will no longer apply and is retired as opposed to being reused.

401 Unauthorized

If invalid credentials are supplied in a request that requires authorization, The 401 Unauthorized status is returned. The situations where this would occur are:

  • No credentials are supplied for a request that requires credentials.
  • The credentials supplied are not valid.

Supplied credentials are considered invalid if one or more of the following situations are true:

  • The JWT audience is invalid.

  • The JWT issuer type is not one of org, dir, or svc.

  • The JWT issuer ID is not valid.

  • The entity identified by the JWT issuer ID does not have an active and non-expired Public Key.

  • The entity identified by the JWT issuer ID or one of its ancestors is not active.

  • The JWT subject type, if specified, is not the same or a child type of the JWT issuer type.

  • The JWT subject is not the same as the JWT issuer and the entity identified by the JWT subject is not a descendant of the

    entity identified by the JWT issuer ID.

  • The entity identified by the JWT subject ID or one of its ancestors is not active.

  • The entity identified by the JWT subject ID is not active.

  • The entity identified by the JWT subject ID does not have an active Public Key.

Example:

HTTP/1.1 401 Unauthorized
X-IOV-JWT: eyJhbGciOiJSU0EtT0FFUCIsIm.VuYyI6IkEyNTZHQ00ifQ.OKOawDo13gRp2ojaHV7LF
WWW-Authenticate: IOV-JWT aud=lka
Content-Type: application/html; charset=UTF-8
Content-Length: 0

403 Forbidden

A 403 Forbidden response is returned when the request credentials are valid and the request itself is deemed valid. However, the request is for a resource for which the JWT subject, or JWT issuer (if no JWT subject was provided), does not have the rights to access. This does not mean that the resource itself is valid as there will likely be no validation of the resource.

Example:

HTTP/1.1 403 Forbidden
X-IOV-JWT: eyJhbGciOiJSU0EtT0FFUCIsIm.VuYyI6IkEyNTZHQ00ifQ.OKOawDo13gRp2ojaHV7LF
Content-Type: application/html; charset=UTF-8
Content-Length: 0

404 Resource Not Found

A 404 Resource Not Found error is returned when the request requires an entity or resource that does not exist. There will not be any relevant data in the response.

Example:

HTTP/1.1 403 Forbidden
X-IOV-JWT: eyJhbGciOiJSU0EtT0FFUCIsIm.VuYyI6IkEyNTZHQ00ifQ.OKOawDo13gRp2ojaHV7LF
Content-Type: application/html; charset=UTF-8
Content-Length: 0

405 Method Not Allowed

A 405 Method Not Allowed is returned when calling a valid endpoint with the wrong HTTP method. There will not be any relevant data in the response.

408 Request Timed Out

A 408 Request Timed Out is returned when you request access to an element that is part of an put-of-band process that did not complete in the time period allotted.

429 Too Many Requests

A 429 Too Many Requests is returned when the request has a rate limit and that limit is exceeded.

User Contributed

LaunchKey links to user contributed code as a resource to its community. LaunchKey does not in any way guarantee or warrant the quality and security of these code bases. User contributed code is supported by the creators. If you do find a link from the site to user contributed code that is malicious or inappropriate in any way, please report that link to LaunchKey immediately and we will investigate the claim. Submit any issue to LaunchKey support at https://launchkey.com./support. ×