Codice motivo stabile
Un codice di errore stabile viene utilizzato nella logica del client, nei report e nell'instradamento automatico delle richieste di assistenza.
Documentazione / Errori API
Gestione degli errori API
Schema unificato per risposte, codici di errore, problemi temporanei, risultati sconosciuti, diagnostica e ripristino sicuro nelle integrazioni iGaming.
HTTP
risultato della richiesta
Codici
motivo chiaro
Riprova
azione sicura
Ricerca
diagnostica della richiesta
Ciclo di gestione degli errori
Dalla risposta API al ripristino
01
Determinare il tipo di risultato
Controllare lo stato HTTP, il codice del motivo, la categoria di errore e lo stato dell'operazione.
02
Salvare i dati per l'analisi
Registrare gli identificatori della richiesta e dell'operazione, l'endpoint, l'ora, il riferimento del provider e i parametri sicuri.
03
Scegliere un'azione sicura
Correggere i dati, interrompere l'operazione, ripetere la richiesta dopo una pausa o verificare lo stato corrente.
04
Ripristinare e verificare
Evitare duplicati, eseguire la riconciliazione, avvisare i responsabili e chiudere la causa del problema.
Panoramica
Un errore deve spiegare la causa e l'azione successiva
Una sola risposta HTTP 400 o 500 non è sufficiente. Un'API affidabile restituisce un codice motivo stabile, collega la risposta all'identificatore della richiesta e permette di capire se occorre correggere i dati, interrompere l'operazione, ripetere la richiesta o verificarne separatamente lo stato.
Azione prevedibile
La categoria di errore indica se la richiesta può essere ripetuta e quali dati devono essere modificati.
Collegamento per la diagnostica
Gli identificatori della richiesta, dell'operazione e del provider collegano i log del client ai sistemi interni e all'assistenza.
Struttura dell'errore
Struttura consigliata della risposta di errore
La risposta deve essere compatta, stabile e adatta all'elaborazione automatica senza rivelare l'implementazione interna o dati sensibili.
Codice di errore
Identificatore stabile del motivo che non cambia quando viene modificato il messaggio esplicativo.
Descrizione
Breve spiegazione sicura senza codice interno, query al database, segreti o dettagli non necessari.
ID richiesta
Identificatore univoco per trovare l'operazione nei log e nelle richieste di assistenza.
Dati aggiuntivi
Stato consentito, limite, stato corrente o motivo sicuro del rifiuto.
Può essere ripetuta
Indicazione esplicita di un errore temporaneo che non elimina la protezione contro l'esecuzione ripetuta dell'operazione.
Pausa prima del nuovo tentativo
Ritardo consigliato in secondi o header HTTP per il rate limiting e l'indisponibilità temporanea.
Errori dei campi
Elenco dei campi problematici con codice motivo, percorso del valore e spiegazione sicura.
Link alla documentazione
Link permanente o identificatore della sezione con la descrizione del motivo e la modalità di correzione.
Categorie di errore
Principali categorie di errore
Lo stato HTTP indica la classe generale del risultato, mentre il codice interno specifica il motivo concreto e l'azione consentita.
Errore nei dati di input
Formato non valido, campo obbligatorio mancante, valore non supportato, precisione dell'importo o struttura della richiesta non valida.
Errore di autenticazione
Token, chiave API o firma mancanti, scaduti o non validi, ora della richiesta errata o identificatore monouso non valido.
Autorizzazioni insufficienti
Il client è riconosciuto ma non dispone del ruolo, brand, mercato o permesso necessario per l'azione.
Oggetto non trovato
Il giocatore, il pagamento, il round, la verifica KYC, il provider o un altro oggetto non esiste oppure non è accessibile al client.
Conflitto di stato
La versione o lo stato dell'oggetto sono cambiati oppure l'identificatore dell'operazione è già stato utilizzato con parametri diversi.
Violazione di una regola di business
Saldo insufficiente, limite superato, giocatore bloccato, mercato vietato o transizione di stato non consentita.
Troppe richieste
È stato superato il numero consentito di richieste per client, metodo, ruolo o operazione critica.
Provider non disponibile
Il servizio esterno non è disponibile, risponde in ritardo o temporaneamente non accetta operazioni.
Errore interno
Errore imprevisto della piattaforma senza rivelare dettagli interni, ma con un identificatore per la diagnostica.
Riprova e ripristino
Ripetizione della richiesta e risultato sconosciuto
La ripetizione è sicura solo dopo aver determinato il tipo di errore e verificato se l'operazione iniziale potrebbe essere già stata eseguita.
01
Verificare se la ripetizione è consentita
Gli errori di dati, autorizzazioni e regole di business richiedono normalmente la correzione della richiesta, non un nuovo invio.
02
Mantenere la stessa chiave dell'operazione
La ripetizione di un'operazione finanziaria, di gioco o di un'altra operazione critica non deve creare un nuovo risultato.
03
Aumentare la pausa tra i tentativi
Gli intervalli aumentano gradualmente, tengono conto del tempo indicato dal server e limitano il numero complessivo di tentativi.
04
Interrompere e inoltrare alla verifica
Dopo l'esaurimento dei tentativi, l'operazione viene registrata come incompleta e inoltrata alla verifica manuale o alla riconciliazione.
L'assenza di risposta non significa che l'operazione sia stata rifiutata
Se la connessione si interrompe dopo l'invio della richiesta, il risultato può rimanere sconosciuto. Prima di ripetere, occorre verificare lo stato tramite l'identificatore dell'operazione o attendere una notifica attendibile.
Diagnostica e controllo
Log, identificatori, metriche e notifiche
La diagnostica deve ricostruire il percorso della richiesta tra piattaforma, adattatore e provider esterno senza conservare dati sensibili non necessari.
Contesto per l'analisi
Identificatori della richiesta, di correlazione, dell'operazione e del provider esterno.
Endpoint, metodo HTTP, ambiente, client, orario e durata della risposta.
Stato HTTP, codice di errore, numero di tentativi e stato finale.
Campi sensibili mascherati, header sicuri e risultato della verifica della firma.
Monitoraggio e notifiche
Tasso di errori per metodo, provider, client e categoria del motivo.
Aumento delle risposte lente, degli HTTP 5xx, delle firme non valide e dei limiti di frequenza.
Numero di tentativi ripetuti, operazioni con risultato sconosciuto e attività di ripristino.
Notifiche con soglie, responsabili e regole di escalation.
Test
Cosa verificare nell'ambiente di test
L'ambiente di test deve riprodurre ogni categoria di errore importante e confermare il corretto comportamento del client, dei nuovi tentativi e dei controlli.
Errori nei dati di input
Campi mancanti, tipi errati, valori non supportati, precisione dell'importo e più errori contemporaneamente.
Accesso e autorizzazioni
Chiave non valida, token scaduto, firma errata, ruolo non autorizzato, IP vietato e identificatore monouso ripetuto.
Nessuna risposta e risultato sconosciuto
Interruzione della connessione prima dell'invio, dopo la presa in carico dell'operazione e durante la ricezione della risposta finale.
Rate limiting
HTTP 429, pausa consigliata, richieste parallele e ripristino dopo la fine del limite.
Errori del provider
Indisponibilità, manutenzione, risposta non valida, notifica ritardata e stato contraddittorio.
Ripetizione e arresto di protezione
Limite del numero di tentativi, aumento delle pause, sospensione temporanea delle richieste, ripristino controllato ed escalation manuale del problema.
Checklist prima del lancio
L'integrazione in produzione viene avviata dopo aver verificato struttura degli errori, comportamento del client, protezione dai duplicati e diagnostica.
Tutti gli errori restituiscono un codice motivo stabile e un identificatore della richiesta.
I dettagli degli errori non rivelano segreti o implementazione interna.
Le categorie di errore temporanee e permanenti sono descritte nella documentazione.
La ripetizione di un'operazione critica utilizza la stessa chiave di protezione dai duplicati.
Un risultato sconosciuto viene gestito tramite verifica dello stato o una notifica attendibile.
Sono configurati log, metriche, notifiche, coda di ripristino e regole di escalation.
Vuoi uniformare gli errori API?
Fornisci le attuali risposte HTTP, i codici di errore, le regole di retry e gli scenari problematici. APIACE ti aiuterà a definire un modello di errore unificato, un ripristino sicuro e i relativi controlli.