Skip to content

Error Codes

  • Find the code

    Match the code returned by your client.

  • Read the meaning

    Check its message and channel status.

  • Take action

    Use retry and support guidance.

An error code connects a failed request to its meaning and protocol status.

Look up a code below; preserve the error identifier when reporting a failure.

Next: Retry and support

This page documents all error codes returned by IdentityScribe. Each code includes the message shown to clients and protocol-specific status codes.

CONFLICTfailure codeHTTP 409ConflictLDAP 51busyHTTP statusLDAP result
CONFLICTfailure codeHTTP 409ConflictLDAP 51busyHTTP statusLDAP result
One failure code maps to each protocol's native status.

When an error occurs on HTTP-based channels (REST, GraphQL), clients receive:

HeaderDescriptionExample
Error-IdUnique error identifier (UUID)a1b2c3d4-e5f6-7890-abcd-ef1234567890
Error-CodeMachine-readable error codeDIRECTORY_BUSY
Error-KindError classificationUNAVAILABLE
Correlation-IdRequest correlation ID (if provided)req-12345
Trace-IdOpenTelemetry trace IDabc123def456...
Span-IdOpenTelemetry span IDabc123def456
Retry-AfterRetry hint (for retryable errors)2 or Tue, 13 Jan 2026 12:00:00 GMT

The Retry-After header uses either:

  • Seconds: delay before retrying (e.g., 5)
  • HTTP-date: specific time to retry (RFC 1123 format)
{
"error": {
"status": 503,
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"timestamp": "2026-01-13T10:30:00.123Z",
"code": "DIRECTORY_BUSY",
"kind": "UNAVAILABLE",
"message": "Directory service is busy. Please retry later.",
"correlation": "req-12345",
"trace_id": "abc123def456...",
"span_id": "abc123def456",
"retry": {
"after": "PT2S"
}
}
}

Field Notes:

  • message — Client-safe, always present
  • details — Never sent to HTTP clients; recorded in the wide log failure block below
  • correlation, trace_id, span_id — Present only if set on the request
  • retry — Present only for retryable errors, contains after (ISO 8601 duration) or at (ISO 8601 instant)

When errors are logged to wide logs (JSON format), the failure block contains:

{
"trace_id": "abc123def456...",
"span_id": "abc123def456",
"duration_seconds": 0.234,
"result": "unavailable",
"failure": {
"kind": "UNAVAILABLE",
"code": "DIRECTORY_BUSY",
"trace_id": "abc123def456...",
"span_id": "abc123def456",
"message": "Directory is busy processing another request",
"details": { "pending_operations": 5 }
},
"scribe.operation": "LDAP.Search",
"scribe.channel": "ldap"
}

General error codes returned when no more specific code applies.

Operation was cancelled, typically by the caller.

Message: Request cancelled.

ProtocolStatus
HTTP499 Client Closed Request
LDAP118 (cancelled)

Client specified an invalid argument.

Messages: Depending on the failure, clients receive one of these messages. An ellipsis marks details that vary by request:

  • Malformed GraphQL JSON request.
  • Unknown attributes: …
  • Some inputs are invalid.
ProtocolStatus
HTTP400 Bad Request
LDAP2 (protocolError)

Client specified an argument that is outside allowed range.

Message: That value is out of range.

ProtocolStatus
HTTP400 Bad Request
LDAP19 (constraintViolation)

Operation was rejected because the system is not in a state required for execution.

Message: Can’t do that right now.

ProtocolStatus
HTTP409 Conflict
LDAP19 (constraintViolation)

Request does not have valid authentication credentials.

Messages: Depending on the failure, clients receive one of:

  • Authentication required.
  • Please sign in and try again.
ProtocolStatus
HTTP401 Unauthorized
LDAP49 (invalidCredentials)

Caller does not have permission to execute the operation.

Message: You don’t have access to do that.

ProtocolStatus
HTTP403 Forbidden
LDAP50 (insufficientAccessRights)

Requested entity was not found.

Message: Not found.

ProtocolStatus
HTTP404 Not Found
LDAP32 (noSuchObject)

Entity that a client attempted to create already exists.

Message: That already exists.

ProtocolStatus
HTTP409 Conflict
LDAP68 (entryAlreadyExists)

Concurrency conflict, such as read-modify-write conflict.

Message: That conflicts with an existing value.

ProtocolStatus
HTTP409 Conflict
LDAP51 (busy)

Resource has been exhausted (e.g., quota, rate limit).

Message: Too many requests. Try again in a bit.

Retry: Recommended after 2s

ProtocolStatus
HTTP429 Too Many Requests
LDAP51 (busy)

Deadline expired before operation could complete.

Message: Timed out. Please try again.

Retry: Recommended after 1s

ProtocolStatus
HTTP504 Gateway Timeout
LDAP3 (timeLimitExceeded)

Service is currently unavailable.

Message: Service temporarily unavailable. Please try again.

Retry: Recommended after 5s

ProtocolStatus
HTTP503 Service Unavailable
LDAP52 (unavailable)

Operation is not implemented or not supported.

Message: That isn’t supported.

ProtocolStatus
HTTP501 Not Implemented
LDAP53 (unwillingToPerform)

Internal errors (unexpected).

Message: Something went wrong.

ProtocolStatus
HTTP500 Internal Server Error
LDAP80 (other)

Unrecoverable data loss or corruption.

Message: A data error occurred.

ProtocolStatus
HTTP500 Internal Server Error
LDAP80 (other)

Unknown error.

Message: Something went wrong.

ProtocolStatus
HTTP500 Internal Server Error
LDAP80 (other)

Errors returned for malformed or invalid request parameters.

Invalid JSON syntax in request parameter.

Message: Some inputs are invalid.

ProtocolStatus
HTTP400 Bad Request
LDAP2 (protocolError)

Wrong JSON value type (e.g., expected ARRAY, got OBJECT).

Message: Some inputs are invalid.

ProtocolStatus
HTTP400 Bad Request
LDAP2 (protocolError)

Invalid element type in array (e.g., expected STRING, got NUMBER).

Message: Some inputs are invalid.

ProtocolStatus
HTTP400 Bad Request
LDAP2 (protocolError)

Required field missing in JSON object.

Message: Some inputs are invalid.

ProtocolStatus
HTTP400 Bad Request
LDAP2 (protocolError)

Mutually exclusive parameters specified together.

Message: Some inputs are invalid.

ProtocolStatus
HTTP400 Bad Request
LDAP2 (protocolError)

Invalid value format (not a JSON syntax error, but value doesn’t match expected format).

Message: Some inputs are invalid.

ProtocolStatus
HTTP400 Bad Request
LDAP2 (protocolError)

Errors returned when parsing filter expressions.

General filter parse failure.

Message: Invalid filter syntax.

ProtocolStatus
HTTP400 Bad Request
LDAP2 (protocolError)

SCIM attribute path not supported (e.g., dotted paths like name.familyName).

Message: Unsupported attribute path in filter.

ProtocolStatus
HTTP400 Bad Request
LDAP2 (protocolError)

Unsupported filter feature (e.g., ComplexValueFilter).

Message: Unsupported filter feature.

ProtocolStatus
HTTP400 Bad Request
LDAP2 (protocolError)

Filter nesting depth exceeds limit.

Message: Filter nesting depth exceeded.

ProtocolStatus
HTTP400 Bad Request
LDAP2 (protocolError)

Filter string exceeds maximum length.

Message: Filter too large.

ProtocolStatus
HTTP400 Bad Request
LDAP2 (protocolError)

Errors related to directory query execution and resource limits.

Directory connection permits exhausted

Message: Directory service is busy. Please retry later.

Retry: Recommended after 2s

ProtocolStatus
HTTP503 Service Unavailable
LDAP51 (busy)

Result set exceeded size limit

Message: Size limit exceeded.

Retry: Not recommended

ProtocolStatus
HTTP429 Too Many Requests
LDAP4 (sizeLimitExceeded)

Query exceeded time limit

Message: Timed out. Please try again.

Retry: Recommended after 1s

ProtocolStatus
HTTP504 Gateway Timeout
LDAP3 (timeLimitExceeded)

Unsupported attribute operation in filter/sort

Message: Some inputs are invalid.

ProtocolStatus
HTTP400 Bad Request
LDAP2 (protocolError)

Base DN outside configured scopes

Message: That value is out of range.

ProtocolStatus
HTTP400 Bad Request
LDAP19 (constraintViolation)

Query requires but lacks type constraint

Message: Some inputs are invalid.

ProtocolStatus
HTTP400 Bad Request
LDAP2 (protocolError)

Inconsistent type constraints in query

Message: Some inputs are invalid.

ProtocolStatus
HTTP400 Bad Request
LDAP2 (protocolError)

Temporal lookup filter is not a single supported identifier constraint

Message: Invalid temporal lookup query.

ProtocolStatus
HTTP400 Bad Request
LDAP2 (protocolError)

Directory continuation state failed an internal consistency check

Message: The search failed an internal consistency check.

ProtocolStatus
HTTP500 Internal Server Error
LDAP80 (other)

Errors specific to REST API endpoints.

Missing required path parameter

Message: Some inputs are invalid.

ProtocolStatus
HTTP400 Bad Request
LDAP2 (protocolError)

Invalid/blank path parameter

Message: Some inputs are invalid.

ProtocolStatus
HTTP400 Bad Request
LDAP2 (protocolError)

Unknown entry type requested

Message: Not found.

ProtocolStatus
HTTP404 Not Found
LDAP32 (noSuchObject)

Invalid identifier format - not a valid UUID, UOID, or DN

Message: Parameter ‘id’ must be a GlobalId, UUID, UOID, or DN.

ProtocolStatus
HTTP400 Bad Request
LDAP2 (protocolError)

Single-entry lookup failed after request validation

Messages: Depending on the failure, clients receive one of:

  • Entry lookup failed. Contact an administrator if this continues.
  • Entry comparison failed. Contact an administrator if this continues.
ProtocolStatus
HTTP500 Internal Server Error
LDAP80 (other)

Pagination params not allowed in export mode

Messages: Depending on the failure, clients receive one of:

  • Export is disabled
  • Invalid first/limit value
ProtocolStatus
HTTP400 Bad Request
LDAP2 (protocolError)

Invalid export options JSON

Messages: Depending on the failure, clients receive one of:

  • Export options exceed maximum size
  • Invalid export options JSON
  • Invalid arrays option
  • Invalid delimiter option
  • Invalid newline option
  • Invalid quote option
  • Invalid wrapColumn option
  • Invalid headerComment option
  • Unknown export option
  • Invalid export option type
  • Invalid arraySep option
  • Invalid nulls option
  • Invalid export format
ProtocolStatus
HTTP400 Bad Request
LDAP2 (protocolError)

Export format in export param conflicts with Accept header

Message: Export format conflict

ProtocolStatus
HTTP400 Bad Request
LDAP2 (protocolError)

Invalid filename (invalid chars, path traversal)

Message: Some inputs are invalid.

ProtocolStatus
HTTP400 Bad Request
LDAP2 (protocolError)

Path traversal detected in filename

Message: Some inputs are invalid.

ProtocolStatus
HTTP400 Bad Request
LDAP2 (protocolError)

Export requires explicit field list

Message: Some inputs are invalid.

ProtocolStatus
HTTP400 Bad Request
LDAP2 (protocolError)

Wildcard fields not allowed in export mode

Message: Some inputs are invalid.

ProtocolStatus
HTTP400 Bad Request
LDAP2 (protocolError)

Export exceeded row or duration limit

Messages: Depending on the failure, clients receive one of:

  • Export row limit exceeded
  • Export time limit exceeded

Retry: Recommended after 2s

ProtocolStatus
HTTP429 Too Many Requests
LDAP51 (busy)

Invalid idPrefix (non-https, private IP)

Message: Invalid idPrefix URL

ProtocolStatus
HTTP400 Bad Request
LDAP2 (protocolError)

Errors returned when serving static assets.

Asset path is missing or blank

Message: Not found.

ProtocolStatus
HTTP404 Not Found
LDAP32 (noSuchObject)

Invalid path characters or traversal attempt

Message: Some inputs are invalid.

ProtocolStatus
HTTP400 Bad Request
LDAP2 (protocolError)

Unsupported file extension

Message: Not found.

ProtocolStatus
HTTP404 Not Found
LDAP32 (noSuchObject)

Asset not found at path

Message: Not found.

ProtocolStatus
HTTP404 Not Found
LDAP32 (noSuchObject)

IO error reading asset content

Message: Something went wrong.

ProtocolStatus
HTTP500 Internal Server Error
LDAP80 (other)

Token is malformed or cannot be parsed as JWT.

Message: Invalid token format.

ProtocolStatus
HTTP401 Unauthorized
LDAP49 (invalidCredentials)

Token signature is invalid.

Message: Invalid token signature.

ProtocolStatus
HTTP401 Unauthorized
LDAP49 (invalidCredentials)

Token has expired (exp claim).

Message: Token has expired.

ProtocolStatus
HTTP401 Unauthorized
LDAP49 (invalidCredentials)

Token is not yet valid (nbf claim).

Message: Token is not yet valid.

ProtocolStatus
HTTP401 Unauthorized
LDAP49 (invalidCredentials)

Token issuer is not recognized.

Message: Unknown token issuer.

ProtocolStatus
HTTP401 Unauthorized
LDAP49 (invalidCredentials)

Token audience doesn’t match any expected value.

Message: Invalid token audience.

ProtocolStatus
HTTP401 Unauthorized
LDAP49 (invalidCredentials)

JWKS could not be fetched or parsed.

Message: Token validation unavailable.

Retry: Recommended after 5s

ProtocolStatus
HTTP503 Service Unavailable
LDAP52 (unavailable)

Generic token validation error.

Messages: Depending on the failure, clients receive one of:

  • Token validation failed.
  • Authentication temporarily unavailable.
  • Authentication timed out.
  • Authentication failed.
ProtocolStatus
HTTP401 Unauthorized
LDAP49 (invalidCredentials)

Cookie encryption failed.

Message: Something went wrong.

ProtocolStatus
HTTP500 Internal Server Error
LDAP80 (other)

Cookie decryption failed (invalid or corrupted).

Message: Please sign in and try again.

ProtocolStatus
HTTP401 Unauthorized
LDAP49 (invalidCredentials)

Cookie envelope is expired.

Message: Please sign in and try again.

ProtocolStatus
HTTP401 Unauthorized
LDAP49 (invalidCredentials)

Query depth exceeds configured max-depth limit.

Message: Query is too deep.

ProtocolStatus
HTTP400 Bad Request
LDAP2 (protocolError)

Query complexity exceeds configured max-complexity limit.

Message: Query is too complex.

ProtocolStatus
HTTP400 Bad Request
LDAP2 (protocolError)

Query string exceeds parser max-characters limit.

Message: Query is too large.

ProtocolStatus
HTTP400 Bad Request
LDAP2 (protocolError)

Query has too many tokens (exceeds parser max-tokens limit).

Message: Query has too many tokens.

ProtocolStatus
HTTP400 Bad Request
LDAP2 (protocolError)