Cod stabil al motivului
Un cod de eroare stabil este utilizat în logica clientului, rapoarte și distribuirea automată a solicitărilor.
Documentație / Erori API
Gestionarea erorilor API
Un model unificat pentru răspunsuri, coduri de eroare, defecțiuni temporare, rezultate necunoscute, diagnosticare și recuperare sigură pentru integrările iGaming.
HTTP
rezultatul solicitării
Coduri
motiv clar
Repetare
acțiune sigură
Căutare
diagnosticarea solicitării
Ciclul de gestionare a erorilor
De la răspunsul API la recuperare
01
Stabiliți tipul rezultatului
Verificați starea HTTP, codul motivului, categoria erorii și starea operațiunii.
02
Salvați datele pentru analiză
Înregistrați identificatorii solicitării și operațiunii, endpoint-ul, ora, referința furnizorului și parametrii siguri.
03
Alegeți o acțiune sigură
Corectați datele, opriți operațiunea, repetați solicitarea după o pauză sau verificați starea curentă.
04
Recuperare și verificare
Evitați duplicatele, efectuați reconcilierea, notificați persoanele responsabile și închideți cauza problemei.
Prezentare generală
Eroarea trebuie să explice cauza și acțiunea următoare
Un simplu răspuns HTTP 400 sau 500 nu este suficient. Un API fiabil returnează un cod stabil al motivului, leagă răspunsul de un identificator al solicitării și permite înțelegerea clară a faptului dacă trebuie corectate datele, oprită operațiunea, repetată solicitarea sau verificată separat starea acesteia.
Acțiune previzibilă
Categoria erorii arată dacă solicitarea poate fi repetată și ce date trebuie modificate.
Corelare pentru diagnosticare
Identificatorii solicitării, operațiunii și furnizorului leagă jurnalele clientului de sistemele interne și de suport.
Structura erorii
Structura recomandată a răspunsului de eroare
Răspunsul trebuie să fie compact, stabil și potrivit pentru prelucrare automată, fără a dezvălui implementarea internă sau date sensibile.
Codul erorii
Un identificator stabil al motivului, care nu se modifică atunci când mesajul explicativ este editat.
Descriere
O explicație scurtă și sigură, fără cod intern, interogări către baza de date, secrete sau detalii inutile.
ID solicitare
Un identificator unic pentru găsirea operațiunii în jurnale și contactarea suportului.
Date suplimentare
O stare permisă, o limită, starea curentă sau un motiv sigur al refuzului.
Poate fi repetată
Un indicator explicit al unei erori temporare care nu elimină protecția operațiunii împotriva executării repetate.
Pauză înainte de repetare
O întârziere recomandată în secunde sau un antet HTTP pentru limitarea frecvenței și indisponibilitatea temporară.
Erori de câmp
O listă a câmpurilor problematice, cu un cod al motivului, calea către valoare și o explicație sigură.
Referință la documentație
Un link permanent sau un identificator de secțiune care descrie cauza și modul de remediere.
Categorii de erori
Principalele categorii de erori
Starea HTTP indică clasa generală a rezultatului, iar codul intern precizează cauza concretă și acțiunea permisă.
Eroare de validare a datelor de intrare
Format incorect, câmp obligatoriu lipsă, valoare neacceptată, precizie incorectă a sumei sau structură invalidă a solicitării.
Eroare de autentificare
Token lipsă, expirat sau invalid, cheie API, semnătură, marcaj temporal al solicitării sau nonce incorect.
Permisiuni insuficiente
Clientul este recunoscut, dar nu are rolul, brandul, piața sau permisiunea necesară pentru acțiune.
Obiectul nu a fost găsit
Un jucător, o plată, o rundă, o verificare KYC, un furnizor sau alt obiect nu există ori nu este disponibil clientului.
Conflict de stare
Versiunea sau starea obiectului s-a modificat ori identificatorul operațiunii a fost deja utilizat cu alți parametri.
Încălcarea unei reguli de afaceri
Sold insuficient, limită depășită, jucător blocat, piață interzisă sau tranziție de stare nepermisă.
Prea multe solicitări
A fost depășit numărul permis de solicitări pentru client, metodă, rol sau operațiune critică.
Furnizor indisponibil
Serviciul extern este indisponibil, răspunde cu întârziere sau temporar nu acceptă operațiuni.
Eroare internă
O eroare neașteptată a platformei, fără dezvăluirea detaliilor interne, dar cu un identificator pentru diagnosticare.
Repetare și recuperare
Repetarea solicitării și rezultat necunoscut
Repetarea este sigură numai după identificarea tipului de eroare și verificarea dacă operațiunea inițială s-ar fi putut deja finaliza.
01
Verificați dacă repetarea este permisă
Erorile de date, permisiuni și reguli de afaceri necesită de obicei corectarea solicitării, nu retrimiterea acesteia.
02
Păstrați aceeași cheie a operațiunii
Repetarea unei operațiuni financiare, de joc sau a altei operațiuni critice nu trebuie să creeze un rezultat nou.
03
Măriți pauza dintre încercări
Intervalele cresc treptat, respectă timpul indicat de server și limitează numărul total de încercări.
04
Opriți și trimiteți spre verificare
După epuizarea încercărilor, operațiunea este înregistrată ca nefinalizată și trimisă pentru verificare manuală sau reconciliere.
Lipsa unui răspuns nu înseamnă că operațiunea a eșuat
Dacă legătura se întrerupe după trimiterea solicitării, rezultatul poate rămâne necunoscut. Înainte de repetare, verificați starea după identificatorul operațiunii sau așteptați o notificare de încredere.
Diagnosticare și control
Jurnale, identificatori, indicatori și notificări
Diagnosticarea trebuie să reconstruiască traseul solicitării între platformă, adaptor și furnizorul extern, fără stocarea unor date sensibile inutile.
Context pentru analiză
Identificatorii solicitării, corelării, operațiunii și furnizorului extern.
Endpoint-ul, metoda HTTP, mediul, clientul, ora și durata răspunsului.
Starea HTTP, codul erorii, numărul de încercări și starea finală.
Câmpuri sensibile mascate, antete sigure și rezultatul validării semnăturii.
Monitorizare și notificări
Rata erorilor după metodă, furnizor, client și categoria motivului.
Creșterea răspunsurilor lente, erorilor HTTP 5xx, semnăturilor invalide și evenimentelor de limitare a frecvenței.
Numărul de repetări, operațiunilor cu rezultat necunoscut și sarcinilor de recuperare.
Notificări cu praguri, responsabili și reguli de escaladare.
Testare
Ce trebuie verificat în mediul de testare
Mediul de testare trebuie să reproducă fiecare categorie importantă de eroare și să confirme comportamentul corect al clientului, repetărilor și mecanismelor de control.
Erori de validare a datelor de intrare
Câmpuri lipsă, tipuri invalide, valori neacceptate, precizia sumei și mai multe erori simultane.
Acces și permisiuni
Cheie invalidă, token expirat, semnătură incorectă, rol neautorizat, IP blocat și nonce reutilizat.
Fără răspuns și rezultat necunoscut
Întreruperea conexiunii înainte de trimitere, după acceptarea operațiunii și în timpul primirii răspunsului final.
Limitarea frecvenței
HTTP 429, pauza recomandată, solicitări paralele și recuperarea după expirarea limitării.
Erori ale furnizorului
Indisponibilitate, mentenanță, răspuns incorect, notificare întârziată și stare contradictorie.
Repetare și oprire de protecție
Limitarea numărului de încercări, creșterea pauzelor, oprirea temporară a solicitărilor, recuperarea controlată și escaladarea manuală.
Listă de verificare înainte de lansare
Integrarea de producție este lansată după verificarea structurii erorilor, comportamentului clientului, protecției împotriva duplicatelor și diagnosticării.
Toate erorile returnează un cod stabil al motivului și un identificator al solicitării.
Detaliile erorilor nu dezvăluie secrete sau implementarea internă.
Categoriile de erori temporare și permanente sunt descrise în documentație.
Repetarea unei operațiuni critice utilizează aceeași cheie de idempotentă.
Un rezultat necunoscut este gestionat prin verificarea stării sau printr-o notificare de încredere.
Sunt configurate jurnalele, indicatorii, notificările, coada de recuperare și regulile de escaladare.
Trebuie standardizate erorile API?
Trimiteți răspunsurile HTTP actuale, codurile de eroare, regulile de repetare și scenariile problematice. APIACE vă va ajuta să definiți un model unificat de erori, recuperarea sigură și controlul.