15.5Status codes and errors

Last updated 9 October 2026

Success codes

Status	Meaning
`200 OK`	The request succeeded; the body holds the result.
`201 Created`	An object was created; `Location` points at it.
`202 Accepted`	The change was not carried out yet: it is waiting for approval. See below.
`204 No Content`	The change succeeded and there is nothing to return (for example a password reset).
`207 Multi-Status`	A batch ran, but some items failed. See "Batch operations".

Error responses

Errors are returned as RFC 7807 problem details, with the gateway's own error code in errorCode:

json

{
  "title": "Validation",
  "status": 400,
  "detail": "Attribute 'departmnt' does not exist in the Active Directory schema for object class 'user'.",
  "errorCode": "AD.Attributes.ValidationError",
  "metadata": {
    "detail": "Attribute 'departmnt' does not exist in the Active Directory schema for object class 'user'."
  }
}

status and title give the HTTP status and the error category.
detail is a human-readable message.
errorCode is a stable, machine-readable code. Branch on errorCode, not on detail.
metadata carries details where there are any. When a request fails its input rules, it holds propertyName, attemptedValue and allErrors, which lists every failure. A rejected password is never echoed back.

Three answers are not problem details: the X-Client-Id refusals described above (error and message), and the licence refusal, { "error": "Forbidden", "code": "License.NotActivated", "message": "An active licence is required to perform Active Directory operations." }, which carries its code in code rather than errorCode.

Status	Category	Typical cause
`400`	Validation	Invalid input, an unknown attribute, a disabled operation.
`401`	Unauthorized	Missing or invalid credential.
`403`	Forbidden	Missing permission, directory not allowed, no licence.
`404`	NotFound	The object or operation does not exist (or is not yours to see).
`409`	Conflict	The change conflicts with the directory's state, for example a name already in use.
`413`	—	The request body is too large.
`429`	TooManyRequests	A rate limit was reached. Retry after the `Retry-After` header.
`500`	Internal	An unexpected server error.
`502`	External	The domain controller refused or failed the request.
`504`	Timeout	The domain controller did not answer in time.

Error codes worth handling

Code	Status	Meaning and what to do
Input validation codes	400	Fix the input named in `metadata.propertyName`.
`AD.Attributes.ValidationError`	400	An attribute is unknown, system-only, security-sensitive or of the wrong type.
`Operation.Disabled`	400	An administrator has switched this operation off. Nothing was queued; retrying will not help.
`AD.Attributes.TooMany`, `AD.Attributes.TooManyValues`, `AD.Attributes.ValueTooLong`	400	The request exceeds the attribute limits (see "Limits").
`AD.Attributes.ReadForbidden`	403	The request asked to read a protected credential attribute or an attribute blocked by an attribute policy, or used one in an LDAP filter.
`AD.Attributes.Protected`	403	An attribute policy makes an attribute the request writes read-only or blocked. `metadata.attributes` names each one with the rule's reason. Nothing was changed; retrying will not help.
`Agent.ApprovalImpossible`	403	The change would have to wait for approval, but it carries a password, which must never be stored while waiting. See below.
`License.NotActivated` (in `code`)	403	The installation has no active licence; directory operations are refused.
`Request.BodyTooLarge`	413	The body exceeds the route's size limit; `maxBodyBytes` gives the limit.
`DirectoryBatch.TooManyItems`, `DirectoryBatch.Empty`	400	A batch has more than 100 items, or none.
`OrganizationUnitAccounts.TooMany`	400	More than 100 accounts would change in one organizational-unit run.

Last updated 9 October 2026