Error Handling in eSign B2B

Overview

The B2B API uses standard HTTP response codes to communicate the result of a request and error codes and messages to inform about the details in case of problems.

Error Response Format

All errors follow a standardized JSON response format:

{
    "error":             "Error code e.g. 'internal_error -- SIG_BB###'",
    "error_description": "Error message",
    "error_reference":   "Error reference for further investigation"
}

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

Note that there are two kinds of error codes that can be shown: - A short text-code will always be sent which also gives a hint about the nature of the problem. - A BankID-code in the format SIG_BB### is appended in most cases. This code should be mentioned together with the error reference when reporting a problem to BankID support.

The BankID-code will be omitted for errors in connection with DPoP to be compliant with error responses defined in RFC9449.

Error Code	Description	HTTP Status	Category
json_validation_error -- SIG_BB600	Request parameter validation failed	400	Validation errors
json_validation_error -- SIG_BB601	Request parameter validation failed	400	Validation errors
json_validation_error -- SIG_BB602	Request parameter validation failed	400	Validation errors
use_dpop_header	Authentication missing DPoP-header	401	Validation errors
insufficient_scope -- SIG_BB604	Access token missing required scope	403	Validation errors
invalid_token	DPoP token missing or invalid	401	Validation errors
invalid_dpop_proof	DPoP proof missing or invalid	401	Validation errors
invalid_request -- SIG-BB607	Request uses unsupported data structure	400	Validation errors
invalid_request -- SIG-BB608	CMSes and/or OCSPs have wrong format	400	Validation errors
internal_error -- SIG_BB699	Internal error	400	Validation errors
backend_service_unavailable -- SIG_BB800	Internal error	503	Technical and communication errors
internal_error -- SIG_BB801	Internal error	500	Technical and communication errors
internal_error -- SIG_BB802	Internal error	500	Technical and communication errors
backend_service_error -- SIG_BB803	Internal error	500	Technical and communication errors
backend_service_error -- SIG_BB804	Internal error	500	Technical and communication errors
internal_error -- SIG_BB899	Internal error	500	Technical and communication errors

How to Fix Errors? What to Do?

How to react to errors depends on the error code, the HHTP status code or the category of the error.

SIG_BB600, SIG_BB601, SIG_BB602 (HTTP 400)

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

use_dpop_header, invalid_token, invalid_dpop_proof (HTTP 401)

Use the correct token plus authentication using DPoP including the DPoP proof and try again. If the problem persists, contact BankID support.

SIG_BB604 (HTTP 403)

Use a token with the correct scope and try again. If the problem persists, contact BankID support.

SIG-BB607, SIG-BB608 (HTTP 400)

Note: This only concerns the endpoint /sdo_from_cmses.

Make sure the data structure in the request body matches one of those defined in the API documentation.

Additionally, CMSes and OCSP made for Pades are not accepted for SDOs in this endpoint.

Category 'Technical and communication errors' and SIG_BB699

These are all internal errors that can occur during the signing process. If the problem persists, contact BankID support.