Error Handling and Troubleshooting

The Issuer Service uses standard HTTP status codes and JSON error responses. A global error filter normalizes every failure into a consistent JSON body, so clients can rely on the same shape across all endpoints.

Common Status Codes:

• 400 Bad Request: Invalid request parameters or missing fields (for example, a credential schema whose name contains spaces, or a credential offer with an empty credentialConfigurationIds array). The global validation pipe also rejects any JSON property that is not part of the endpoint's schema, with a message like property X should not exist.

• 401 Unauthorized: A missing, malformed, or expired OIDC JWT Bearer token, or a token whose signature cannot be verified against the configured JWKS endpoint.

• 403 Forbidden: The token is valid but lacks the required admin role (accepted from realm_access.roles or a resource_access client-role entry) on a route that enforces it, or it does not grant ownership of the requested holder.

• 404 Not Found: A non-existent schema ID (GET /schemas/:schemaId) or a request for a hosted DID document that does not exist. Unknown issuer, session, or credential-offer identifiers currently surface as 500 rather than 404.

• 409 Conflict: A schema with the same name and version already exists (POST /schemas).

• 410 Gone: The requested schema version has been superseded by a newer version. Retrieve it by passing includeInactive=true on the schema endpoint.

• 429 Too Many Requests: The global rate limit (60 requests per 60 seconds) has been exceeded. DID document serving is exempt from this limit.

• 500 Internal Server Error: Unexpected server issues.

Example Error Response:

{
  "statusCode": 410,
  "message": "Schema version is superseded.",
  "error": "Gone",
  "path": "/schemas/[email protected]",
  "timestamp": "2026-06-22T10:15:30.000Z"
}

Error bodies always include statusCode, message, path, and timestamp; responses produced by standard HTTP exceptions additionally include an error label (for example, "Gone" for 410 or "Conflict" for 409).

Troubleshooting Tips:

• Validate request payloads against your credential schema definitions before sending. For SD-JWT credentials, ensure the vct claim is present in the signing payload.

• Ensure the request carries a current, unexpired OIDC JWT Bearer token in the Authorization: Bearer <token> header. The admin role is required only on the agent/DID/issuer/verifier/holder management routes (/agent/*) and the cloud-wallet routes (/holders/:holderId/*).

• For 401 errors, confirm the JWKS endpoint (OIDC_JWKS_URL) is reachable, that the token's kid header matches a key published by that endpoint, and that the token has not expired.

• For 403 errors on a management or holder route, confirm the token includes the admin role in realm_access.roles or in a resource_access client-role entry, and that the holder you are addressing belongs to the authenticated user.

• For 410 errors, the schema version is superseded. Use includeInactive=true to read the old version, or reference the current active version returned by GET /schemas/:schemaName/versions.

• Verify database connectivity (DATABASE_URL) — the service stores schemas, sessions, signing keys, and hosted DID documents in PostgreSQL.

• Check service logs for detailed error messages. Server-side failures (5xx) are logged with a stack trace; client errors (4xx) are logged as warnings.

If issues persist, review your environment configuration (DATABASE_URL, ISSUER_BASE_URL, OIDC_JWKS_URL), your schema definitions, and network connectivity between the service and its OIDC provider.