API Errors

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

400 Bad Request

HTTP status 400 Bad Request will be 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 will include 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 you supplied is not valid. This can occur when attempting to perform an operation involving a Directory User and the identifier you supplied in the request was not valid.
DIR-002:No longer in use
DIR-003:No longer in use
DIR-004:Internal use only
DIR-005:Internal use only
KEY-001:The public key you supplied is not valid. When attempting to add a Public Key to an entity, the Pubic Key you provided is not a valid RSA Public Key.
KEY-002:The public key you supplied already exists. It cannot be added again. This occurs when you are trying to add a Public Key to an entity but the Public Key had already been added before.
KEY-003:The key_id you supplied could not be found. This occurs when you attempt to update an existing Public Key for an entity but the ID you 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 you attempt 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 does is not associated with the subject Directory. This occurs when attempting to remove an SDK Key from a Directory which does not contain the SDK Key in question.
SVC-001:When attempting to add or rename a Service, the name you requested was already in use.
SVC-002:During an auth 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:You attempted to modify or delete a Service entity or Service entity child Entity for a non-existent Service.

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 will be returned. The situations in which this would occur are:

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

Credentials being supplied would be considered invalid if one or more of the following is 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 will be returned when the request credentials are valid and the request itself has been 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 will be 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 will be returned when you are calling a valid endpoint with the wrong HTTP method. There will not be any relevant data in the response. There will not be any relevant data in the response.

408 Request Timed Out

A 408 Request Timed Out will be 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 will be returned when the request has a rate limit and that limit has been 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. ×