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#

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. 1

   Verify that the iss parameter matches the expected DIP issuer URL (RFC 9207)

2. 2

   Read the error and error_description parameters

3. 3

   Display an appropriate message to the user

4. 4

   For temporarily_unavailable, consider retrying the flow after a short delay

5. 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. 1

   The complete error message

2. 2

   Your client_id

3. 3

   The request that caused the error (with sensitive values redacted)