Error codes
This page lists the HTTP error responses that wallets encounter during verification and issuance flows with the Truvity EUDIW Connector. Some errors originate from the connector and others from the authorization server.
Wallet-facing error responses
When the connector encounters an error while processing a wallet request, it returns a JSON response with an error field and the corresponding HTTP status code.
| Error code | HTTP status | Description |
|---|---|---|
invalid_request | 400 | Validation errors during request parsing or format validation |
invalid_request | 403 | Cryptographic validation failures (signatures, key binding, nonce) or trust chain validation failures |
server_error | 500 | Infrastructure errors (database, key management) |
temporarily_unavailable | 503 | Transient errors (downstream service timeouts) |
The invalid_request error code maps to two HTTP statuses because it covers two distinct failure categories defined by OID4VP. Use the HTTP status code to distinguish them: 400 indicates a malformed or missing request parameter, while 403 indicates a cryptographic or trust validation failure.
Error description field
Error responses may include an optional error_description field with a human-readable explanation of the error. This field provides additional context for debugging but is not guaranteed to be present in every response.
Issuance error codes
The connector and the authorization server return the following error codes to wallets during OID4VCI credential issuance flows.
Wallet-facing issuance error responses
| Error code | HTTP status | When returned | Resolution |
|---|---|---|---|
invalid_proof | 400 | Key Proof JWT is structurally invalid (wrong signature, aud mismatch, or expired iat) | Wallet creates a new Key Proof with the correct audience and a fresh timestamp |
invalid_nonce | 400 | c_nonce in Key Proof is invalid or expired | Wallet requests a fresh c_nonce from the nonce endpoint and retries |
unknown_credential_configuration | 400 | credential_configuration_id not found in Credential Issuer Metadata | Check that the credential configuration matches a configured type |
unknown_credential_identifier | 400 | credential_identifier not recognized (not found in the session or not matching any known configuration) | Check that the credential identifier matches a value from the token response |
invalid_credential_request | 400 | Credential request payload is malformed (missing required parameters, unsupported values) | Check request body structure against the OID4VCI specification |
invalid_grant | 400 | Pre-authorized code expired or already used, invalid tx_code, or session not found | Check offer expiration, verify tx_code delivery, confirm the offer has not been redeemed |
invalid_token | 401 | Access token invalid, expired, or DPoP thumbprint mismatch | Wallet must obtain a new token |
invalid_request | 400 | Request contains invalid parameters (for example, unsupported tx_code input mode) | Check request parameters against the API documentation |
server_error | 500 | Infrastructure errors (database, key management) | Retry after delay |
temporarily_unavailable | 503 | Transient errors (authorization server or credential signing service unavailable) | Wallet retries after delay |
use_dpop_nonce | 400 | DPoP nonce required. Returned by the authorization server at the token endpoint | Wallet retries with the server-provided nonce from the DPoP-Nonce response header |
Further reading
- Callback events—verification and issuance callback event statuses and payload fields
- Connector architecture—how the connector processes requests and delivers results
- Handle verification and issuance errors—implement error handling and retry logic
- Issue a credential—issue a credential of any type using the management API