# Error Handling in BankID CSC Signing API

## Overview

The BankID CSC Signing API uses two different error response formats depending on the endpoint:

- **CSC endpoints** (`/credentials/*`, `/signatures/*`, `/info`) return errors in CSC format.
- **OAuth endpoints** (`/oauth2/token`, `/oauth2/authorize`) return errors in OAuth 2.0 format (RFC 6749).

## CSC Endpoint Errors

### Error Response Format

All CSC endpoint errors follow this JSON format:

```json
{
    "errorCode": "error_code_here",
    "errorDescription": "Human-readable description of the error",
    "errorReference": "REF123456789"
}
```

`errorCode`: Error code classifying the problem (see table below).

`errorReference`: Unique reference to a particular error occurrence — please state this when contacting BankID support.

### Error Codes

| Error Code                    | Description                                                                                                              | HTTP Status | Category           |
| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------ | ----------- | ------------------ |
| `invalid_request`             | The request is missing a required parameter, includes an invalid parameter value, or is otherwise malformed              | 400         | Request Validation |
| `invalid_parameters`          | One or more request parameters are invalid or missing                                                                    | 400         | Request Validation |
| `invalid_credential_id`       | The credential ID is invalid or not found                                                                                | 400         | Request Validation |
| `invalid_sad`                 | The Signature Activation Data (SAD) is invalid                                                                           | 400         | Request Validation |
| `invalid_hash_algorithm`      | The hash algorithm is not supported                                                                                      | 400         | Request Validation |
| `invalid_signature_format`    | The signature format or algorithm is not supported                                                                       | 400         | Request Validation |
| `hash_mismatch`               | The number of hashes does not match `numSignatures`                                                                      | 400         | Request Validation |
| `document_too_large`          | The request payload exceeds the maximum allowed size                                                                     | 413         | Request Validation |
| `token_already_used`          | The access token has already been used at this endpoint. Each token must follow the required endpoint order exactly once | 400         | Token Lifecycle    |
| `authentication_required`     | Authentication is required to access this resource                                                                       | 401         | Authentication     |
| `invalid_token`               | The access token is invalid, expired, or malformed                                                                       | 401         | Authentication     |
| `insufficient_scope`          | The access token does not have the required scope                                                                        | 403         | Authorization      |
| `credential_not_found`        | The specified credential was not found                                                                                   | 404         | Credential         |
| `credential_locked`           | The credential is locked or suspended                                                                                    | 403         | Credential         |
| `credential_expired`          | The credential has expired                                                                                               | 403         | Credential         |
| `certificate_not_found`       | The certificate was not found                                                                                            | 404         | Credential         |
| `certificate_expired`         | The certificate has expired                                                                                              | 403         | Credential         |
| `certificate_revoked`         | The certificate has been revoked                                                                                         | 403         | Credential         |
| `certificate_creation_failed` | Certificate generation failed during credential creation                                                                 | 500         | Signing Backend    |
| `signing_limit_exceeded`      | The signing limit has been exceeded                                                                                      | 403         | Signing            |
| `signature_validation_failed` | The signature validation failed                                                                                          | 422         | Signing            |
| `unsupported_operation`       | The operation is not supported for this credential type                                                                  | 501         | Signing            |
| `csc_service_error`           | Error occurred while communicating with the signing backend                                                              | 500         | Service            |
| `csc_service_timeout`         | The signing backend did not respond in time                                                                              | 500         | Service            |
| `csc_service_unavailable`     | The signing backend is temporarily unavailable                                                                           | 503         | Service            |
| `csc_user_keys_limit`         | The signing backend key generation limit has been reached. Retry after a short delay                                     | 503         | Service            |
| `service_unavailable`         | The service is temporarily unavailable                                                                                   | 503         | Service            |
| `internal_error`              | An internal server error occurred                                                                                        | 500         | Internal           |

### How to Fix Errors? What to Do?

How to react to errors depends on the category of the error.

**Category 'Request Validation'**

This is a request validation error due to missing or invalid parameter values. Fix the request according to the error description and try again. If the problem persists, contact BankID support.

**Category 'Token Lifecycle'**

The access token has been used out of order or reused at an endpoint. Each access token must follow the required endpoint sequence: `credentials/list` then `credentials/authorize` then `signatures/signHash`. If you receive `token_already_used`, you need to start a new signing session by obtaining a fresh access token. See [Token single-use](https://docs.stoe.no/bankid-esign-provider/apis/csc/CSC.md#token-single-use) for details.

**Category 'Authentication'**

Use the correct token and authentication data and try again. If the problem persists, contact BankID support.

**Category 'Authorization'**

Ensure the access token has the required scope. If the problem persists, contact BankID support.

**Category 'Credential'**

The credential or certificate is not available, has expired, or has been revoked. Verify the credential ID and its status. If the problem persists, contact BankID support.

**Category 'Signing Backend' and 'Signing'**

These errors occur during the signing process. If the problem persists, contact BankID support.

**Category 'Service'**

The service or signing backend is temporarily unavailable. Retry after a short delay. For `csc_user_keys_limit`, the signing backend has reached its key generation capacity — retry after a brief wait. If the problem persists, contact BankID support.

**Category 'Internal'**

Technical problems. Contact BankID support.

## OAuth Token Endpoint Errors

### Error Response Format

Errors from `POST /oauth2/token` follow the OAuth 2.0 error format (RFC 6749):

```json
{
    "error": "error_code_here",
    "error_description": "Human-readable description of the error"
}
```

### Error Codes

| Error Code                | Description                                                                                        | HTTP Status |
| ------------------------- | -------------------------------------------------------------------------------------------------- | ----------- |
| `invalid_request`         | The request is missing a required parameter or includes an invalid parameter value                 | 400         |
| `invalid_client`          | Client authentication failed                                                                       | 401         |
| `invalid_grant`           | The authorization code is invalid, expired, or the code_verifier does not match the code_challenge | 400         |
| `unauthorized_client`     | The client is not authorized to use this grant type                                                | 400         |
| `unsupported_grant_type`  | The grant type is not supported                                                                    | 400         |
| `server_error`            | The server encountered an unexpected condition                                                     | 500         |
| `temporarily_unavailable` | The service is temporarily unavailable                                                             | 503         |

## OAuth Authorize Endpoint Errors

### Error Response Format

Errors from `GET /oauth2/authorize` are delivered as query parameters in the redirect back to the `redirect_uri`:

```
https://your-redirect-uri?error=access_denied&error_description=User+denied+the+request&state=your-state
```

### Error Codes

| Error Code                  | Description                                                                        |
| --------------------------- | ---------------------------------------------------------------------------------- |
| `invalid_request`           | The request is missing a required parameter or includes an invalid parameter value |
| `access_denied`             | The user denied the authorization request                                          |
| `unsupported_response_type` | The response type is not supported                                                 |
| `invalid_scope`             | The requested scope is invalid or unknown                                          |
| `server_error`              | The server encountered an unexpected condition                                     |
| `temporarily_unavailable`   | The service is temporarily unavailable                                             |