Error handling
When an error is returned by backend it is composed of an HTTP status code which is used to give a general hint of the cause of the error. In general; most endpoints may return the following non-successful http status codes:
| Status code | Name | Description |
|---|---|---|
| 400 | Bad request | The input is either malformed, incomplete or in direct conflict with business rules that would never accept the input. No use to retry the operation without changing the input. |
| 401 | Unauthorized | The supplied credentials are either invalid, expired or not enough for this request. Either new credentials or additional credentials are needed to be accepted. |
| 403 | Forbidden | The caller is identified, but the caller with the current credentials is not allowed to perform this action. Additional privileges may be needed to be allowed to make this call. |
| 409 | Conflict | The request cannot be completed due to the input being in conflict with existing other data or configuration. The request could be successful if the conflicting data or configuration is changed. |
| 500 | Internal server error | This is a server side error and cannot be resolved by the caller. Please retry the operation or raise a support ticket. |
Additional information is also returned in response as application/json. The json object carries more detailed information about failure. For business related problems where the caller could mitigate the issue an ErrorCode is returned by the service.
These ErrorCode are detailed in their respective openapi specification and is also detailed below in the next section.
Error code registry
| Error code | Description | Mitigation |
|---|---|---|
| AUTHENTICATION_FAILED | Unable to authenticate the caller. | Invalid or missing credentials provided. Please provide valid credentials. |
| TOKEN_MALFORMED | The used token is malformed. | Invalid or malformed token provided. Please provide valid credentials. |
| TOKEN_EXPIRED | The used token is expired. | Please issue a new token and retry the call. |
| TOKEN_REVOKED | The used token is revoked. | Please issue a new token and retry the call. |
| INVALID_IDP | The provided idpKey does not exist or it not enabled. | Either the input is invalid or the application identity provider configuration should be updated to include the given identity provider. |
| MALFORMED_INPUT | The provided input or resource path is invalid or missing. | Please align input data with the rules defined by the endpoint specification. See error details for further hints to which parameter that is malformed. |
| MALFORMED_IDP_CONFIGURATION | The used idp configuration is malformed. | The used idp configuration by the given idp key is either malformed or is missing configuration to complete this request. Please review the used idp configuration. |
| UNSUPPORTED_APPLICATION | The used token is not bound to an application which this endpoint accepts. | This endpoint does not accept calls from the application that was used when the token was issued. Issue another token for an application which this endpoint accept. |
| FIREWALL_ACCESS_DENIED | The application firewall actively refused the request. | If this error was unintended, then either additional credentials are required or the application firewall may need reconfiguration to allow the request. |
| MISSING_PERMISSION | The caller does not have the required permission to perform the request. | If this error was unintended, then the caller either need additional access or the used role(s) may need additional privileges. |
| DATA_ACCESS_DENIED | The attempted call does not have the required data access to manipulate this resource. | Either input needs to be changed or additional privileges might be needed for the caller. Check if the intended change is aligned with business rules. |
| RULE_VIOLATION | The attempted call is in conflict with a permission rule. | Either input needs to be changed or additional privileges might be needed for the caller. Check if the intended change is aligned with business rules. |
| INVALID_CAPTCHA | The call does not carry a valid captcha token or it has already been used. | Supply a new valid captcha token. |
| INVALID_CLAIM | The used invite is either malformed, invalid, expired or does not exist. | Request a new valid invite to be used and reattempt the call. |
| CLAIMED_INVITE | The used invite has already been used. | The request may have been repeated; see if the intended invite is already completed. If not; request a new invite to be used. |
| WITHDRAWN_INVITE | The used invite has been withdrawn. | Request a new invite to be used. |
| EXPIRED_INVITE | The used invite has expired. | Request the current invite to be extended or request a new invite to be used. |
| APPLICATION_NOT_ACTIVE | The referenced application is not ACTIVE. | If possible and if intended; please reactivate the application prior to making this call. |
| TENANT_NOT_ACTIVE | The referenced tenant is not ACTIVE. | If possible and if intended; please reactivate the tenant prior to making this call. |
| NOT_A_LEAF_NODE | The intended change is only allowed on leaf nodes. | If possible and if intended; see if the any child nodes can be removed prior to making this call. |
| NODE_DISABLED | The referenced node is DISABLED and no change is allowed. | If possible and if intended; please enable the node prior to making this call. |
| NODE_HIERARCHY_DEPTH_EXCEEDED | The change would exceed the allowed node hierarchy depth. | Check if the nodes could be structured in another way and also if the intended change is aligned with business rules. |
| ILLEGAL_STATUS_TRANSITION | The intended status change is in conflict with current business rules. | You may need to perform another status change prior to making this transition. Check if the intended change is aligned with business rules. |
| ILLEGAL_ACTOR_STATUS | The intended change is not allowed for the current actor status. | You may need to perform another status change prior to making call. Check if the intended change is aligned with business rules. |
| ILLEGAL_ACTOR_INVITE_STATUS | The intended change is not allowed for given invite. | Check if the intended change is aligned with business rules. |
| NO_SUCH_ACCOUNT | The referenced account does not exist. | Either the input is malformed or no access to account. |
| NO_SUCH_APPLICATION | The referenced application does not exist. | Either the input is malformed or no access to application. |
| NO_SUCH_TENANT | The referenced tenant does not exist. | Either the input is malformed or no access to tenant. |
| NO_SUCH_ROLE | The referenced role does not exist. | Either the input is malformed or the application role configuration should be updated to include the given role. |
| NO_SUCH_ROLE_TEMPLATE | The referenced role template does not exist. | No role template exists with the given name. |
| NO_SUCH_SERVICE_DEFINITION | The referenced service definition does not exist. | Either the input is malformed or the application service definition configuration should be updated to include the given service definition. |
| NO_SUCH_SERVICE_PERMISSION | The referenced service permission does not exist. | Either the input is malformed or the application service definition configuration should be updated to include the given service permission. |
| NO_SUCH_APPLICATION_ROLE_DEFINITION | The referenced application role definition configuration does not exist. | Either the input is malformed or the application role definition configuration should be updated to include the given role. |
| NO_SUCH_APPLICATION_IDENTITY_CONFIG | The referenced application identity provider configuration does not exist. | Either the input is malformed or the application identity provider configuration should be updated to include the given identity provider. |
| NO_SUCH_APPLICATION_FIREWALL_RULE | The referenced application firewall rule does not exist. | Either the input is malformed or the application firewall rule configuration should be updated to include the given firewall rule. |
| NO_SUCH_IDP | The referenced application identity provider does not exist. | Either the input is malformed or the identity provider configuration should be updated to include the given identity provider. |
| NO_SUCH_ADMINISTRATOR | The referenced administrator does not exist. | Either the input is malformed, the administrator does not exist or no access to administrator. |
| NO_SUCH_ACTOR | The referenced actor does not exist. | Either the input is malformed, the actor does not exist or no access to actor. |
| NO_SUCH_NODE | The referenced node does not exist. | Either the input is malformed, the node does not exist or no access to node. |
| NO_SUCH_INVITE | The referenced invite does not exist. | Either the input is malformed or the invite does not exist. |
| NO_ADMINISTRATOR_INVITE | The referenced administrator does not have any invitation. | If the administrator account is not yet used then a new invitation can be created for said administrator. |
| NO_ACTOR_IDENTITY_MATCH | The caller is authenticated by no active actor identity exists in said tenant. | The caller needs to be associated to a new or an existing actor prior to attempting this call. |
| DUPLICATE_CUSTOM_ID | A custom identifier is already taken by another entry. | Either the input is malformed or the custom identifier which is already used on another entry should be removed prior to making this call. |
| DUPLICATE_IDENTITY | An identity entry is already taken by another entry. | Either the input is malformed or the identity which is already used on another entry should be removed prior to making this call. |
| USERNAME_ALREADY_USED | The supplied username is already used. | You may already have an account or another end user has reserved this username. |
| POLICY_VIOLATION | The supplied policy configuration either contains malformed configuration or the input data is in conflict with existing policy rules. | Either the input needs to be changed or the policy configuration in conflict needs to be updated. |
| TOO_MANY_FIREWALL_AUTH_KEYS | The change will exceed the maximum allowed firewall authorization keys. | Remove another non-used authorization key to allow for a new entry to be created. |
| TOO_MANY_APPLICATIONS | The change will exceed the maximum allowed applications. | Remove another non-used application to allow for a new entry to be created. |
| TOO_MANY_TENANTS | The change will exceed the maximum allowed tenants. | Remove another non-used tenant to allow for a new entry to be created. |
| TOO_MANY_TAGS | The change will exceed the maximum allowed tags. | Remove another non-used tag to allow for a new entry to be created. |
| TOO_MANY_REQUESTS | Too many requests made to the service, please try again later. | Throttle your requests to keep within the allowed requests per time period window. |
| DECOMMISSIONED_PRIOR_DELETE | Not possible to delete entry before setting its state to DECOMMISSIONED. | Decommission this entry prior to attempting to delete it. |