# 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)