API errors

Authorization Hub uses standard HTTP status codes. Most error responses include a JSON body that describes the problem. The body format depends on which service produced the error.

Error formats

Authorization Hub errors

Errors from the Hub service and the API gateway use the following format:

{
  "status": "NOT_FOUND",
  "errorCode": "ATTRIBUTE_NOT_FOUND",
  "errorMessage": ["Attribute not found by resource.department"],
  "timestamp": "2026-10-13T09:15:30.123+02:00[Europe/Athens]"
}

Field	Description
status	The name of the HTTP status, for example BAD_REQUEST, NOT_FOUND, CONFLICT, or UNPROCESSABLE_CONTENT.
errorCode	A stable, machine-readable code. Use it, rather than the message, in your error handling.
errorMessage	An array of one or more human-readable messages. Validation errors list every problem found.
timestamp	The time of the error.

Domain manager errors

Errors from the domain manager endpoints (/api/adm) use a different format:

{
  "code": 400,
  "message": "Could not create a domain due to errors in the policy",
  "details": "[\"ERROR:mismatched input '<EOF>' expecting '}' (file:/test.alfa line : 1 column : 325)\"]"
}

Field	Description
code	The HTTP status code.
message	A human-readable message.
details	Optional. Present when ALFA policies fail to compile. It is a string that lists each compiler error.

Responses without a body

Some responses have no body:

• 401. The request has no valid access token. Request a new token and try again.
• 404 with an empty body. A request in My workspace changes an item that does not exist.

Common status codes

Status	Meaning
200, 201, 204	The request succeeded. 201 is returned when a resource is created and 204 when there is nothing to return.
202	The change was saved to My workspace and has not been applied to the project yet.
400	The request is invalid. See the errorMessage for each problem.
401	The access token is missing, invalid, or has expired.
403	The caller is not allowed to perform the request. See Permissions.
404	The resource does not exist, or you do not have access to it.
409	The request conflicts with the current state. For example, the item already exists, or the promoted workspace conflicts with changes made by others.
422	The request was understood but its content failed validation, such as when a workspace is promoted.
503	A dependent service, such as the domain manager, is unavailable.

Gateway errors

The API gateway checks the license and the caller's project access before it forwards a request.

Status	errorCode	Cause
403	MISSING_PROJECT_ID	The request does not include the X-Project-Id header.
403	PROJECT_FORBIDDEN_ACTION	The caller is not a member of the project, the project does not exist, or the caller's project role does not allow the request.
403	LICENSE_EXPIRED	The license has expired. GET /api/license/status is not affected. Read License.
500	LICENSE_VERIFICATION_FAILED, LICENSE_NOT_CONFIGURED, LICENSE_FILE_NOT_FOUND	The license cannot be verified. Contact your administrator.

Common Hub service errors

These error codes can be returned by any Hub service endpoint:

Status	errorCode	Cause
400	INVALID_REQUEST	The request body or parameters failed validation. The messages list every problem.
400	INVALID_SORT_FIELD	The sort parameter names a field that cannot be sorted.
400	IMPORT_MALFORMED_JSON	The imported file is not valid JSON.
400	IMPORT_UNSUPPORTED_FORMAT	The imported file is not in a supported format. Only JSON is accepted.
403	INSUFFICIENT_PERMISSIONS	The caller does not have the platform role the endpoint requires.
409	CONCURRENT_MODIFICATION	Another request modified the same resource at the same time. Retry the request.
422	DRAFT_VALIDATION_FAILED	A workspace contains changes that fail validation. Read My workspace and the API.
Varies	EXTERNAL_ERROR	A failure in a dependent service, such as the domain manager. The status and messages come from that service.

Errors that are specific to an area are listed in its endpoint reference.

Handle errors in automation

• Treat 401 as a signal to request a new access token. Read Token expiration.
• Retry 409 with CONCURRENT_MODIFICATION and 503. Do not retry other 4xx responses without changing the request.
• Log the errorCode and every errorMessage entry. The messages name the exact attribute, connector, or file that failed.