La Public API restituisce gli errori nel formato RFC 9457 — Problem Details for HTTP APIs (rfc-editor.org/rfc/rfc9457), con Content-Type: application/problem+json.
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). |
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. |
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 |
.../errors/not-found-error | 404 | Risorsa non trovata | Not found error |
.../errors/resource-gone-error | 410 | Risorsa eliminata | Resource gone error |
.../errors/server-error | 500 | Errore interno del server | Server error |
Ogni pagina elenca i codici TS-xxx associati, esempi di risposta e indicazioni per risolvere il problema.
| Code | HTTP status | type | Detail |
|---|---|---|---|
TS-000 | 500 | server-error | Internal server error. |
TS-001 | 400 | validation-error | Malformed payload. |
TS-002 | 400 | validation-error | Validation data error. |
TS-003 | 400 | validation-error | Relative resource not found. |
TS-004 | 400 | validation-error | Flow data validation error. |
TS-005 | 400 | validation-error | Sign data validation error. |
TS-006 | 400 | validation-error | Attachment already linked to Template. |
TS-007 | 400 | validation-error | On before create function not found. |
TS-008 | 400 | validation-error | Insufficient credits available. |
TS-009 | 410 | resource-gone-error | Certification deleted. |
TS-010 | 404 | not-found-error | Certification not found. |
TS-011 | 400 | validation-error | No certification attachments found. |
TS-012 | 400 | validation-error | A certification has already been created for this upload session token. |
TS-013 | 400 | validation-error | Not all files have been uploaded. |
TS-014 | 500 | server-error | The certification could not be completed after creation. |
TS-901 | 400 | validation-error | This True Link has already been used to create a certification. |
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.
- Controllare il Content-Type della risposta: se è
application/problem+json, parsare il body come oggetto RFC 9457. - Usare
statusper distinguere 4xx (errore del client) da 5xx (errore del server). - Usare
typeper identificare la categoria di errore e consultare la pagina di documentazione corrispondente. - Usare
code(TS-xxx) per log, analytics o messaggi localizzati. - Mostrare all'utente il
detail; usaretitleper etichette generiche.
- RFC 9457 — Problem Details for HTTP APIs
- Content-Type delle risposte di errore:
application/problem+json