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¶

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 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¶

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