Gestione errori REST API — Italia
Errori RFC 7807 problem+json, codici stabili e linee guida sui retry per la REST API in Italia.
Architettura — RFC 7807 problem+json ovunque in Italia
Ogni risposta 4xx/5xx usa Content-Type: application/problem+json con campi: type (URI stabile), title, status, detail, instance (request id) e campi di estensione per tipo. Il type è stabile fra le versioni e linka alla doc con guida retry/fix. Logga sempre instance — il support può tracciarlo end-to-end in meno di un minuto.
Come integrarlo — Catalogo errori comuni
invalid_vat (VIES non corrisponde, retry dopo fix), invalid_sku (non in catalogo Italia, fix), min_qty_violation (sotto MOQ, fix), invalid_tax_rate (non corrisponde a IVA 22%, fix), idempotency_conflict (stessa key, body diverso, fix), insufficient_inventory (escalare o attendere), SdI_unavailable (transitorio, retry con backoff). Catalogo completo su /docs/errors.
Operatività e casi limite — Errori 5xx e idempotenza
Gli errori 5xx significano che la richiesta non è stata committata. Logghiamo request id, allertiamo l'on-call, pubblichiamo incidenti sulla status page. Le idempotency key ti proteggono: i retry con stessa key dopo un 5xx non producono mai doppi addebiti. I nostri SDK fanno retry sui 5xx con backoff esponenziale (max 3 tentativi) — disabilitabile se serve controllo manuale. I fallimenti Sistema di Interscambio (SdI) arrivano asincroni via webhook con hint di retry.
Domande frequenti
Il catalogo errori è stabile?
Sì — i type URI sono versionati e non riusiamo mai un codice. I nuovi sono additivi.
Come correlare i log?
Ogni risposta ha instance = request id (cm-req-…). Passalo al support, tracciamo end-to-end in meno di un minuto.
SDK o HTTP raw?
Gli SDK sollevano eccezioni tipizzate corrispondenti al type URI — di solito più semplice del parsing JSON. HTTP raw va benissimo.
E i validation error?
422 con array errors, una voce per campo errato con codice stabile e messaggio leggibile.
SdI_unavailable?
Transitorio — il nostro gateway bufferizza il payload fattura e fa retry verso SdI. La conferma arriva via webhook.