Error Codes

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

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

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": "Service temporarily unavailable. Please try again.",
    "correlation": "req-12345",
    "trace_id": "abc123def456...",
    "span_id": "abc123def456",
    "details": { "pending_operations": 5 },
    "retry": {
      "after": "PT5S"
    }
  }
}

Field Notes:

• message — Client-safe, always present
• details — Optional structured diagnostics, may be omitted
• 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"
}

• Default codes
• Argument validation
• Filter parsing
• Directory operations
• REST channel
• Asset serving
• GraphQL channel

General error codes returned when no more specific code applies.

Operation was cancelled, typically by the caller.

Message: Request cancelled.

Client specified an invalid argument.

Message: Some inputs are invalid.

Client specified an argument that is outside allowed range.

Message: That value is out of range.

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

Message: Can’t do that right now.

Request does not have valid authentication credentials.

Message: Please sign in and try again.

Caller does not have permission to execute the operation.

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

Requested entity was not found.

Message: Not found.

Entity that a client attempted to create already exists.

Message: That already exists.

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

Message: That conflicts with an existing value.

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

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

Retry: Recommended after 2s

Deadline expired before operation could complete.

Message: Timed out. Please try again.

Retry: Recommended after 1s

Service is currently unavailable.

Message: Service temporarily unavailable. Please try again.

Retry: Recommended after 5s

Operation is not implemented or not supported.

Message: That isn’t supported.

Internal errors (unexpected).

Message: Something went wrong.

Unrecoverable data loss or corruption.

Message: A data error occurred.

Unknown error.

Message: Something went wrong.

Errors returned for malformed or invalid request parameters.

Invalid JSON syntax in request parameter.

Message: Some inputs are invalid.

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

Message: Some inputs are invalid.

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

Message: Some inputs are invalid.

Required field missing in JSON object.

Message: Some inputs are invalid.

Mutually exclusive parameters specified together.

Message: Some inputs are invalid.

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

Message: Some inputs are invalid.

Errors returned when parsing filter expressions.

General filter parse failure.

Message: Invalid filter syntax.

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

Message: Unsupported attribute path in filter.

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

Message: Unsupported filter feature.

Filter nesting depth exceeds limit.

Message: Filter nesting depth exceeded.

Filter string exceeds maximum length.

Message: Filter too large.

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

Result set exceeded size limit

Message: Size limit exceeded.

Retry: Not recommended

Query exceeded time limit

Message: Timed out. Please try again.

Retry: Recommended after 1s

Unsupported attribute operation in filter/sort

Message: Some inputs are invalid.

Base DN outside configured scopes

Message: That value is out of range.

Query requires but lacks type constraint

Message: Some inputs are invalid.

Inconsistent type constraints in query

Message: Some inputs are invalid.

Errors specific to REST API endpoints.

Missing required path parameter

Message: Some inputs are invalid.

Invalid/blank path parameter

Message: Some inputs are invalid.

Unknown entry type requested

Message: Not found.

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

Message: Some inputs are invalid.

Errors returned when serving static assets.

Asset path is missing or blank

Message: Not found.

Invalid path characters or traversal attempt

Message: Some inputs are invalid.

Unsupported file extension

Message: Not found.

Asset not found at path

Message: Not found.

IO error reading asset content

Message: Something went wrong.

Query depth exceeds configured max-depth limit.

Message: Something went wrong.

Query complexity exceeds configured max-complexity limit.

Message: Something went wrong.

Query string exceeds parser max-characters limit.

Message: Something went wrong.

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

Message: Something went wrong.