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:

{
    "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#

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

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

Error Codes#

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#