Skip to content

Common Errors

This page covers common errors you may encounter when integrating with DIP.

Client Assertion Errors

Unexpected claims in client assertion

Error: unexpected claims in client assertion: [claim_name]

Cause: The client assertion contains claims that are not recognized.

Solution: Ensure your client assertion contains only the required claims (iss, sub, aud, exp) and optionally iat, jti, or nbf. Remove any other claims.

Invalid client assertion type

Error: Related to client_assertion_type

Cause: The parameter is missing or incorrect.

Solution: Set client_assertion_type to exactly urn:ietf:params:oauth:client-assertion-type:jwt-bearer.

Issuer/Subject mismatch

Error: iss or sub validation failure

Cause: The iss or sub claim does not match the client_id.

Solution: Set both iss and sub to your client_id.

Algorithm and Key Errors

Invalid algorithm

Error: Related to JWT algorithm

Cause: Using an unsupported signing algorithm.

Solution: Use one of the supported algorithms: ES256, PS256, or EdDSA. Note that RS256 is NOT supported due to FAPI 2.0 requirements.

Key not found

Error: Key ID not found

Cause: The kid in the JWT header doesn't match any registered key.

Solution: Ensure the kid matches a key in your registered JWKS.

Audience and Configuration Errors

Invalid audience

Error: Audience validation failure

Cause: The aud claim doesn't match the DIP base URL.

Solution: Use the DIP base URL, not an endpoint URL.

Request Object Errors

Missing required claims

Error: Missing required claim in request object

Cause: The request object is missing one or more required claims.

Solution: Ensure your request object includes all required claims:

  • iss
  • aud
  • exp
  • client_id
  • response_type
  • redirect_uri
  • scope
  • state
  • nonce
  • code_challenge
  • code_challenge_method
  • claims

Invalid redirect_uri

Error: Redirect URI validation failure

Cause: The redirect_uri doesn't match any registered URI for your client.

Solution: Use a redirect URI that has been registered with DIP for your client.

Token Exchange Errors

Invalid code_verifier

Error: PKCE verification failure

Cause: The code_verifier doesn't match the code_challenge from the original request.

Solution: Ensure you're using the same code_verifier that was used to generate the code_challenge in the PAR request.

Authorization code expired

Error: Code has expired

Cause: The authorization code was not exchanged for tokens within the validity period.

Solution: Complete the token exchange promptly after receiving the authorization code. The code typically expires after a few minutes.

Authorization Callback Errors

During the identity verification flow, errors may be returned to your redirect_uri as query parameters. These are not returned from the PAR or Token endpoints directly, but as redirects back to your application:

https://your-app.example.com/callback?error=access_denied&error_description=Session+expired&state=af0ifjsldkj&iss=https%3A%2F%2F{dip-base-url}

Error Codes

Error Description
access_denied The user aborted the verification, the session expired, or identity verification failed (document or biometric check)
server_error An internal error occurred during the verification flow (e.g., session error or ID token generation failure)
invalid_request A client error occurred during the flow (e.g., invalid request data or consent validation failure)
temporarily_unavailable The ID Check service is temporarily unavailable — the request can be retried

Handling Callback Errors

Your application should check for the error query parameter on the callback URL before attempting a token exchange. If error is present:

  1. Verify that the iss parameter matches the expected DIP issuer URL (RFC 9207)
  2. Read the error and error_description parameters
  3. Display an appropriate message to the user
  4. For temporarily_unavailable, consider retrying the flow after a short delay
  5. For access_denied due to user abort, allow the user to restart the flow

Need More Help?

If you encounter an error not listed here, please contact Stø support with:

  1. The complete error message
  2. Your client_id
  3. The request that caused the error (with sensitive values redacted)