Error Handling and Troubleshooting

Common responses and fixes:

• 401 Invalid access token

  • Missing/invalid Authorization: Bearer <JWT> header

  • Disallowed alg (only RS256/ES256)

  • Missing sub

  • Expired token → header includes WWW-Authenticate: Bearer error="expired_token"

  • JWT_PROVIDER_PUBLIC_KEY misconfigured (must be Base64 DER SPKI)

• 400 Flow init failed

  • QR content is not supported by the server you pointed to

  • Verifier/issuer returned a 4xx → message surfaced in data.errorMessage

• 404 Process not found

  • Wrong or expired processId

  • Confirm called by a different user than the one who initiated

• 422 Proof verification failed (credential import)

  • VC proof invalid or schema missing/mismatched

• 400 Credential subject mismatch

  • Subject DID differs from holder DID and allowForeignSubject=false

• Database connection errors

  • Verify DB_* values and connectivity; run migrations

• did:web configuration errors

  • Ensure DID_WEB_DOMAIN is set

  • If DID_WEB_PORT is set, it must be numeric

Tips:

• Use /health/liveness and /health/readiness to check service and DB

• Use debug endpoints locally to generate a working token quickly