Ogni integrazione con un'API prima o poi incontrerà degli errori. Un'interruzione di rete, un server irraggiungibile, un documento con formato errato: fa parte del lavoro. L'API PSB comunica gli errori tramite codici di stato HTTP standard e risposte JSON strutturate. Inoltre, il PSB dispone di un meccanismo di retry integrato che gestisce automaticamente gli errori temporanei durante la consegna dei documenti.

In questo articolo scoprirai quali codici di stato restituisce il PSB, come interpretare le risposte di errore, quando puoi riprovare in sicurezza e come funziona il meccanismo di retry automatico del PSB.

L'API PSB utilizza codici di stato HTTP standard per indicare il risultato di una richiesta. I codici di stato si dividono in due categorie: errori del client (4xx) che devi correggere tu stesso, ed errori del server (5xx) che puoi riprovare.

Con un errore 4xx il problema è nella richiesta stessa. Reinviare con gli stessi dati produrrà lo stesso risultato. Correggi la causa prima di riprovare.

Un'eccezione alla regola "solo il 5xx è riprovabile": 429 Too Many Requests indica rate limiting ed è riprovabile. Attendi e rispetta l'header Retry-After prima di reinviare la richiesta.

Un errore 5xx indica un problema temporaneo lato server. La richiesta stessa potrebbe essere corretta. Insieme al 429, questi sono gli unici codici di stato per cui ha senso riprovare.

Nota: l'endpoint di invio accetta un massimo di 24 MB per richiesta, incluso l'overhead HTTP. I payload che superano questo limite vengono rifiutati dal web server con un HTTP 500 anziché un 413, perché il rifiuto avviene prima che il livello applicativo esegua la validazione. Tienilo presente con gli allegati codificati in base64: aggiungono circa il 33% alla dimensione del file.

Con un errore 4xx la risposta contiene un corpo JSON che descrive il problema. Queste informazioni ti aiutano a identificare rapidamente la causa.

{
  "error": "Validation failed",
  "message": "The supplied document is not valid UBL 2.1",
  "details": [
    "cbc:InvoiceTypeCode is missing"
  ]
}

Con un errore 5xx la risposta non è sempre strutturata. Basa la tua logica di retry sul codice di stato HTTP, non sul contenuto del corpo.

Non tutti gli errori meritano un retry. La regola generale è semplice: solo i codici di stato 5xx e i timeout di rete meritano un retry. Con errori 4xx devi modificare la richiesta prima di inviarla nuovamente.

La strategia di retry raccomandata è l'exponential backoff: inizia con un tempo di attesa breve e raddoppialo ad ogni tentativo successivo.

Suggerimento: aggiungi una piccola variazione casuale (jitter) al tempo di attesa. Se più client riprovano simultaneamente dopo un'interruzione, il jitter evita che colpiscano tutti il server nello stesso momento.

Combina sempre la tua logica di retry con l'header X-EConnect-DocumentId. Includendo lo stesso documentId ad ogni tentativo, il PSB garantisce che un documento non venga mai elaborato due volte. Se il PSB riceve un documentId già elaborato, restituisce un 409 Conflict come conferma.

Consulta Idempotenza: prevenire invii duplicati per la spiegazione completa e gli esempi di codice.

Oltre alla logica di retry che implementi tu stesso, il PSB ha un proprio meccanismo di retry per la consegna dei documenti. Se il PSB tenta di consegnare una fattura o un ordine al destinatario e quest'ultimo restituisce un errore 5xx, il PSB riprende automaticamente la consegna.

Il PSB effettua fino a 8 tentativi di retry distribuiti su circa 35 ore. Ad ogni tentativo il PSB pubblica un evento per consentirti di monitorare il progresso:

Se hai configurato un webhook per questi topic, ricevi una notifica ad ogni tentativo. Dopo un InvoiceSentError o OrderSentError, è necessaria un'azione manuale: contatta il destinatario o escala tramite eConnect Support.

Suggerimento: iscriviti ai topic InvoiceSentRetry e InvoiceSentError tramite un webhook. In questo modo rilevi immediatamente i problemi di consegna e puoi agire in modo proattivo.

Per i webhook, il PSB utilizza un programma di retry separato. Se il tuo endpoint webhook non è raggiungibile o non restituisce un codice di stato 2xx, il PSB riprova la consegna dell'evento.

Il PSB si aspetta una risposta 2xx dal tuo endpoint entro 100 secondi. Qualsiasi altra risposta (o un timeout) conta come tentativo fallito. Pertanto, elabora i webhook in arrivo il più rapidamente possibile, conferma la ricezione con un 200 OK ed esegui l'elaborazione pesante in modo asincrono in un processo in background.

Nota: se il tuo endpoint non è raggiungibile per un periodo prolungato, il PSB smette di riprovare dopo 5 giorni. Gli eventi persi possono ancora essere recuperati tramite l'endpoint batch. Consulta Batch hooks per maggiori informazioni.

Per le integrazioni che accedono alla PSB da una rete protetta (firewall, proxy, lista di autorizzazione), devono essere consentiti sia gli hostname principali che quelli di failover. everbinding.nl è il dominio legacy di eConnect ed è attivamente utilizzato per il failover PSB.

Inserisci in whitelist tutti e quattro gli hostname sulla porta 443 (HTTPS). Senza gli hostname di failover, una connessione PSB valida può diventare irraggiungibile durante un evento di failover, mentre la PSB stessa è ancora in esecuzione.