# Errori API

La Public API restituisce gli errori nel formato **RFC 9457 — Problem Details for HTTP APIs** ([rfc-editor.org/rfc/rfc9457](https://www.rfc-editor.org/rfc/rfc9457)), con `Content-Type: application/problem+json`.

## Struttura della risposta di errore

Ogni risposta di errore è un JSON con i campi standard RFC 9457 e, dove previsto, campi di estensione.

| Campo | Tipo | Obbligatorio | Descrizione |
|  --- | --- | --- | --- |
| `type` | string | sì | URI che identifica il **tipo** di errore. Punta alla pagina di documentazione dell'errore (vedi [tipi di errore](#tipi-di-errore)). |
| `title` | string | sì | Breve descrizione leggibile del tipo di problema. |
| `status` | number | sì | Codice di stato HTTP (es. 400, 404, 500). |
| `detail` | string | sì | Messaggio leggibile specifico per questa occorrenza. |
| `code` | string | sì | Codice errore applicativo (`TS-xxx`), utile per log e automazioni. |


## Tipi di errore

Il campo **`type`** della risposta contiene un URI che identifica la categoria dell'errore e punta alla pagina di documentazione corrispondente.

| type | HTTP status | Descrizione | Pagina |
|  --- | --- | --- | --- |
| `.../errors/validation-error` | 400 | Payload o parametri non validi | [Validation error](/it/errors/validation-error) |
| `.../errors/not-found-error` | 404 | Risorsa non trovata | [Not found error](/it/errors/not-found-error) |
| `.../errors/resource-gone-error` | 410 | Risorsa eliminata | [Resource gone error](/it/errors/resource-gone-error) |
| `.../errors/server-error` | 500 | Errore interno del server | [Server error](/it/errors/server-error) |


Ogni pagina elenca i codici `TS-xxx` associati, esempi di risposta e indicazioni per risolvere il problema.

## Elenco completo codici errore

| Code | HTTP status | type | Detail |
|  --- | --- | --- | --- |
| `TS-000` | 500 | [server-error](/it/errors/server-error) | Internal server error. |
| `TS-001` | 400 | [validation-error](/it/errors/validation-error) | Malformed payload. |
| `TS-002` | 400 | [validation-error](/it/errors/validation-error) | Validation data error. |
| `TS-003` | 400 | [validation-error](/it/errors/validation-error) | Relative resource not found. |
| `TS-004` | 400 | [validation-error](/it/errors/validation-error) | Flow data validation error. |
| `TS-005` | 400 | [validation-error](/it/errors/validation-error) | Sign data validation error. |
| `TS-006` | 400 | [validation-error](/it/errors/validation-error) | Attachment already linked to Template. |
| `TS-007` | 400 | [validation-error](/it/errors/validation-error) | On before create function not found. |
| `TS-008` | 400 | [validation-error](/it/errors/validation-error) | Insufficient credits available. |
| `TS-009` | 410 | [resource-gone-error](/it/errors/resource-gone-error) | Certification deleted. |
| `TS-010` | 404 | [not-found-error](/it/errors/not-found-error) | Certification not found. |
| `TS-011` | 400 | [validation-error](/it/errors/validation-error) | No certification attachments found. |
| `TS-012` | 400 | [validation-error](/it/errors/validation-error) | A certification has already been created for this upload session token. |
| `TS-013` | 400 | [validation-error](/it/errors/validation-error) | Not all files have been uploaded. |
| `TS-014` | 500 | [server-error](/it/errors/server-error#fallimento-elaborazione-certificazione) | The certification could not be completed after creation. |
| `TS-901` | 400 | [validation-error](/it/errors/validation-error) | This True Link has already been used to create a certification. |


## GET certificazione: fallimento in elaborazione asincrona

Quando **`GET /v1/certifications/{reportId}`** si riferisce a una certificazione **creata con successo** ma **fallita in elaborazione asincrona**, l’API restituisce un **codice HTTP coerente con l’errore** (ad es. **5xx**). Il corpo è **`application/problem+json`** (RFC 9457), con gli stessi campi degli altri errori.

Se in creazione è stato indicato un **`webhook_url`**, la callback in caso di **errore** usa lo **stesso** payload `problem+json` che restituirebbe questa `GET`.

## Come gestire gli errori nel client

1. Controllare il **Content-Type** della risposta: se è `application/problem+json`, parsare il body come oggetto RFC 9457.
2. Usare **`status`** per distinguere 4xx (errore del client) da 5xx (errore del server).
3. Usare **`type`** per identificare la categoria di errore e consultare la pagina di documentazione corrispondente.
4. Usare **`code`** (`TS-xxx`) per log, analytics o messaggi localizzati.
5. Mostrare all'utente il **`detail`**; usare **`title`** per etichette generiche.


## Riferimento

- [RFC 9457 — Problem Details for HTTP APIs](https://www.rfc-editor.org/rfc/rfc9457)
- Content-Type delle risposte di errore: `application/problem+json`