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. |
| 429 | Too many requests | Too many request have been made in the recent time period towards this endpoint or from the specific caller or for this application. Please delay any additional requests for some time. |
| 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 response example
{
"errorId": "4jdESkT9",
"code": "AUTHORIZATION_MISSING_PERMISSION",
"message": "Missing any of the required permission(s): CATALOG/iam.node/permission.node.name.manage",
"details": [
{
"value": "CATALOG/iam.node/permission.node.name.manage",
"message": "No active role with this permission for the supplied token"
}
],
"occurredAt": "2025-04-10T11:28:36.996598345Z"
}
Error code registry
| Error code | Description | Mitigation |
|---|---|---|
| ACTOR_ALREADY_IN_USE | The intended change is not allowed for the current actor status. | The actor has already an established end user identity affiliation. Please use another actor entry if possible. |
| ACTOR_CUSTOM_ID_RESERVED | A custom identifier is already reserved by another actor. | Either the input is malformed or the custom identifier which is already used on another actor should be removed prior to making this call. |
| ACTOR_IDENTITY_RESERVED | An identity entry is already taken by another actor. | The given identity is already reserved by another actor. If this entry should have this identity then the other actor needs to remove their identity prior to making this call. |
| ACTOR_IDP_NOT_FOUND | The referenced identity provider does not exist or is not enabled. | Either the input is malformed or the identity provider configuration should be updated to include or enable the given identity provider. |
| ACTOR_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. |
| ACTOR_NOT_FOUND | The referenced actor does not exist. | Either the input is malformed, the actor does not exist or no access to actor. |
| ACTOR_ROLE_NOT_FOUND | The referenced role does not exist. | Either the input is malformed or the application role configuration should be updated to include the given role. |
| AUTHENTICATION_EXPIRED | The supplied credentials or token is expired. | Please issue a new token and retry the call. |
| AUTHENTICATION_FAILED | Unable to authenticate the caller. Invalid or no credentials provided. | Please provide valid credentials. |
| AUTHENTICATION_IDP_NOT_FOUND | The provided idpKey does not exist or it not enabled in this application. | Either the input is invalid or the application identity provider configuration should be updated to include the given identity provider. |
| AUTHENTICATION_IDP_CONFIG_MALFORMED | 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. |
| AUTHENTICATION_INVALID_APPLICATION | The supplied token is not bound to an application which this endpoint accepts. The 'app' claim in the jwt token is not accepted. | 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. |
| AUTHENTICATION_REVOKED | The supplied credentials or token is revoked. | This error may occur due to the token being explicitly revoked or that the accesses for the associated actor has changed. Please provide new credentials and retry the call. |
| AUTHORIZATION_DATA_ACCESS_DENIED | The attempted call does not have the required data access to manipulate the referenced 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. |
| AUTHORIZATION_INVALID_CAPTCHA | The call does not carry a valid captcha token or it has already been used. | Supply a new valid captcha token. Make sure that the right clientId is used for said captcha token. |
| AUTHORIZATION_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. |
| AUTHORIZATION_NO_ACTOR_IDENTITY_MATCH | The caller is authenticated but no matching active actor entry could be found for given tenant. | The caller needs to be associated to a new or an existing actor prior to attempting this call. The actor cannot be withdrawn or deactivated. |
| AUTHORIZATION_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. |
| BASIC_IDP_USERNAME_RESERVED | The supplied username is already used. | You may already have an account or another end user has reserved this username. |
| 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. |
| IAM_ACCOUNT_NOT_FOUND | The referenced account does not exist. | Either the input is malformed or no access to account. |
| IAM_ADMINISTRATOR_NOT_FOUND | The referenced administrator does not exist. | Either the input is malformed, the administrator does not exist or no access to administrator. |
| IAM_APPLICATION_LIMIT_EXCEEDED | The change will exceed the maximum allowed applications. | Remove another non-used application to allow for a new entry to be created. |
| IAM_APPLICATION_NOT_ACTIVE | The referenced application is not ACTIVE. | If possible and if intended; please reactivate the application prior to making this call. |
| IAM_APPLICATION_NOT_FOUND | The referenced application does not exist. | Either the input is malformed or no access to application. |
| IAM_DECOMMISSIONED_PRIOR_DELETE | Not possible to delete entry before setting its state to DECOMMISSIONED. | Decommission this entry prior to attempting to delete it. |
| IAM_FIREWALL_AUTH_KEY_LIMIT_EXCEEDED | 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. |
| IAM_FIREWALL_RULE_NOT_FOUND | 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. |
| IAM_IDP_NOT_FOUND | 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. |
| IAM_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. |
| IAM_REVOKED_TOKEN_NOT_FOUND | The referenced revoked token does not exists. | Either the input is malformed or the referenced revoked token does not exists or has been purged. |
| IAM_ROLE_NOT_FOUND | 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. |
| IAM_ROLE_TEMPLATE_NOT_FOUND | The referenced role template does not exist. | No role template exists with the given name. |
| IAM_SERVICE_NOT_FOUND | 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. |
| IAM_SERVICE_PERMISSION_NOT_FOUND | 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. |
| IAM_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. |
| IAM_TAG_LIMIT_EXCEEDED | The change will exceed the maximum allowed tags. | Remove another non-used tag to allow for a new entry to be created. |
| IAM_TENANT_LIMIT_EXCEEDED | The change will exceed the maximum allowed tenants. | Remove another non-used tenant to allow for a new entry to be created. |
| IAM_TENANT_NOT_ACTIVE | The referenced tenant is not ACTIVE. | If possible and if intended; please reactivate the tenant prior to making this call. |
| IAM_TENANT_NOT_FOUND | The referenced tenant does not exist. | Either the input is malformed or no access to tenant. |
| IAM_USER_IDENTITY_RESERVED | An identity entry for this user is already used by another user. | The given identity is already reserved by another user. If this user should have this identity then the other user needs to remove their identity prior to making this call. |
| INPUT_MALFORMED | 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. |
| INPUT_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. |
| INVITE_REJECTED | The supplied invite is either malformed, invalid or does not exist. | Request a new valid invite and reattempt the call. |
| INVITE_CLAIMED | The referenced 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. |
| INVITE_EXPIRED | The referenced invite has expired. | Request the current invite to be extended or request a new invite and reattempt the call. |
| INVITE_ILLEGAL_STATE | The intended change is not allowed for given invite. | Check if the intended change is aligned with business rules. |
| INVITE_NOT_FOUND | The referenced invite does not exist. | Either the input is malformed or the invite does not exist. |
| INVITE_WITHDRAWN | The referenced invite has been withdrawn. | Request a new invite to be used. |
| NODE_CUSTOM_ID_RESERVED | A custom identifier is already reserved by another node. | Either the input is malformed or the custom identifier which is already used on another node should 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. |
| NODE_NOT_A_LEAF | 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_NOT_FOUND | The referenced node does not exist. | Either the input is malformed, the node does not exist or no access to node. |