Responses, errors and pagination

Identity uses JSON for successful responses that carry data and for error bodies. A successful operation that has nothing to return uses an empty body.

Status	General meaning
`200 OK`	the request succeeded and the response contains data, or an idempotent protocol operation completed
`201 Created`	a resource was created
`202 Accepted`	an asynchronous import or export was accepted; poll the returned job
`204 No Content`	the mutation succeeded and the response body is empty
`400 Bad Request`	the request shape or a protocol parameter is invalid
`401 Unauthorized`	the supplied client, resource-server or bearer credential is invalid
`403 Forbidden`	the credential is valid but lacks a required scope or live permission
`404 Not Found`	the tenant or requested resource does not exist
`409 Conflict`	the request conflicts with current state or an existing resource
`429 Too Many Requests`	the caller exceeded a rate limit; honor `Retry-After`
`5xx`	Identity could not complete a valid request

Error body

When a JSON error body is returned, it has one stable machine-readable field:


{
  "error": "invalid_request"
}

Branch on the HTTP status and error together. Do not parse human prose and do not infer one failure from another code.

A 401 or 403 response can also carry a WWW-Authenticate header:


HTTP/1.1 403 Forbidden
Content-Type: application/json
WWW-Authenticate: Bearer error="insufficient_scope", scope="identity.admin.users.manage"
Cache-Control: no-store
 
{"error":"insufficient_scope"}

Here, the token is valid but does not contain the named OAuth scope. A response with access_denied instead means the subject has the scope but no longer holds the required live permission.

Pagination

Every Management API and directory collection accepts these query parameters:

Parameter	Type	Default	Constraints
`page`	integer	`0`	zero-based and greater than or equal to 0
`size`	integer	`25`	from 1 through 100

A collection response wraps its records in content and includes enough metadata to request the next page:


{
  "content": [
    {
      "id": "f351511c-11e4-408f-b069-1c58baf673af",
      "subject": "usr_01JY7N8SV4B30TQGB8Y3YH5J9M",
      "email": "ada@example.com",
      "emailVerified": true,
      "status": "ACTIVE",
      "createdAt": "2026-10-13T08:42:11.384Z"
    }
  ],
  "number": 0,
  "size": 20,
  "numberOfElements": 1,
  "totalElements": 41,
  "totalPages": 3,
  "first": true,
  "last": false,
  "empty": false
}

Field	Type	Meaning
`content`	array	records in the current page
`number`	integer	current zero-based page number
`size`	integer	requested maximum records per page
`numberOfElements`	integer	records actually present in `content`
`totalElements`	integer	records matching the collection query
`totalPages`	integer	pages available at the requested `size`
`first`	boolean	this is page 0
`last`	boolean	no later page exists
`empty`	boolean	`content` contains no record

When last is false, request page=number+1 with the same size. Stop when last is true. An empty page can still report a non-zero totalElements when the requested page lies beyond the end.

Clients should use the fields above and ignore additional response members they do not recognize.

Retry behavior

Do not retry 400, 401, 403, 404 or 409 unchanged. Correct the request, refresh or replace the credential, obtain the required authorization, or reconcile the current resource state first.

Retry 429 and transient 5xx failures with bounded exponential backoff and jitter. Honor Retry-After whenever it is present. Use idempotency keys for bulk jobs so a network retry cannot create a second logical operation.

Sensitive responses

Token responses, UserInfo, introspection, native authentication responses and protected management responses use Cache-Control: no-store. Do not put them in shared caches.

Client secrets and resource-server credentials are returned only when issued. Capture them from the successful creation response and store them in the consuming service’s secret manager. Later list calls return metadata and cannot recover the original secret.