# Error Handling in Timestamping APIs

## PAdES-LTA - /v1/timestamp/pades/lta

This API uses standard HTTP response codes to communicate the result of a request.

Unfortunately it is currently not possible to provide more information in case of errors because of backwards-compatibility of the API.

### Error Responses / HTTP Status Codes

For a detailed breakdown of possible responses on a per-request-basis see the [API documentation](https://docs.stoe.no/bankid-esign-provider/apis/timestamp/v1/lta.yaml).

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

How to react to errors depends mostly on the category of the HTTP status code.

**HTTP 401 & 403**

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

**HTTP 400 - returning error message**

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.

**HTTP 400 - returning JSON object**

This is a PDF validation error. Either the PDF document(s) themselves or in combination with the request parameters given cannot be used for signing.

See the response field `conversionErrors` for details. Note that this is done on a per-document-level.

Modify the PDF(s) and/or request parameters to make them fit fo signing. If the problem seems "wrong" or unsolvable contact BankID support.

**HTTP 5xx**

Technical problems, contact BankID support.

## Timestamp Token API - /v1/timestamp/token

This API uses standard HTTP response codes to communicate the result of a request.

It also adds additional information to responses in case of errors.

### Error Response Format

All errors follow a standardized JSON response format:

```json
{
    "message": "Human-readable error description",
    "code": "SIG-TG###",
    "requestId": "unique-request-identifier",
    "errorReference": "unique-error-reference-for-support"
}
```

`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

| Error Code | Description                                          | HTTP Status | Category             |
| ---------- | ---------------------------------------------------- | ----------- | -------------------- |
| SIG-TG001  | General request validation failure                   | 400         | Request Validation   |
| SIG-TG002  | Invalid or missing request parameters                | 400         | Request Validation   |
| SIG-TG003  | Hash value length does not match algorithm           | 400         | Request Validation   |
| SIG-TG004  | Invalid base64 encoding in request                   | 400         | Request Validation   |
| SIG-TG005  | Request body exceeds maximum allowed size            | 400         | Request Validation   |
| SIG-TG006  | Hash algorithm not supported                         | 400         | Request Validation   |
| SIG-TG101  | Authentication required or failed                    | 401         | Authentication       |
| SIG-TG102  | Access token missing required scope                  | 403         | Authorization        |
| SIG-TG103  | Access token has expired                             | 401         | Authentication       |
| SIG-TG201  | Timestamp service temporarily unavailable            | 503         | Network/Connectivity |
| SIG-TG202  | Network timeout communicating with timestamp service | 503         | Network/Connectivity |
| SIG-TG203  | Failed to connect to timestamp service               | 503         | Network/Connectivity |
| SIG-TG301  | Timestamp authority service error                    | 500         | TSA Service          |
| SIG-TG302  | SSL certificate validation failed                    | 500         | TSA Service          |
| SIG-TG303  | RFC 3161 protocol error                              | 500         | TSA Service          |
| SIG-TG401  | Internal system error                                | 500         | Internal System      |
| SIG-TG402  | Service configuration error                          | 500         | Internal System      |
| SIG-TG403  | Data encoding/decoding error                         | 500         | Internal System      |

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

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

**Category 'Request Validation'**

Correct your request according to the error code and try again. If the problem persists, contact BankID support.

**Category 'Authentication'**

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

**Category 'Network/Connectivity'**

Technical problems, contact BankID support.

**Category 'TSA Service'**

Technical problems, contact BankID support.

**Category 'Internal System'**

Technical problems, contact BankID support.