Stabilny kod przyczyny
Stały kod błędu jest wykorzystywany w logice klienta, raportach i automatycznym kierowaniu zgłoszeń.
Dokumentacja / Błędy API
Obsługa błędów API
Spójny model odpowiedzi, kodów błędów, awarii tymczasowych, nieznanych wyników, diagnostyki i bezpiecznego odzyskiwania dla integracji iGaming.
HTTP
wynik żądania
Kody
jasna przyczyna
Ponowienie
bezpieczne działanie
Wyszukiwanie
diagnostyka żądania
Cykl obsługi błędu
Od odpowiedzi API do odzyskania działania
01
Określić typ wyniku
Sprawdzić status HTTP, kod przyczyny, kategorię błędu i stan operacji.
02
Zachować dane do analizy
Zapisać identyfikatory żądania i operacji, adres metody, czas, referencję dostawcy i bezpieczne parametry.
03
Wybrać bezpieczne działanie
Poprawić dane, zatrzymać operację, ponowić żądanie po przerwie lub sprawdzić bieżący stan.
04
Przywrócić działanie i skontrolować
Wykluczyć duplikaty, przeprowadzić uzgodnienie, powiadomić odpowiedzialne osoby i usunąć przyczynę awarii.
Przegląd
Błąd powinien wyjaśniać przyczynę i kolejne działanie
Sama odpowiedź HTTP 400 lub 500 nie wystarcza. Niezawodne API zwraca stabilny kod przyczyny, wiąże odpowiedź z identyfikatorem żądania i pozwala określić, czy należy poprawić dane, zatrzymać operację, ponowić żądanie czy osobno sprawdzić jej stan.
Przewidywalne działanie
Kategoria błędu wskazuje, czy żądanie można ponowić i jakie dane należy zmienić.
Powiązanie do diagnostyki
Identyfikatory żądania, operacji i dostawcy łączą logi klienta z systemami wewnętrznymi i wsparciem.
Struktura błędu
Zalecana struktura odpowiedzi z błędem
Odpowiedź powinna być zwięzła, stabilna i odpowiednia do automatycznego przetwarzania bez ujawniania implementacji wewnętrznej ani danych wrażliwych.
Kod błędu
Stabilny identyfikator przyczyny, który nie zmienia się po edycji komunikatu objaśniającego.
Opis
Krótkie i bezpieczne wyjaśnienie bez kodu wewnętrznego, zapytań do bazy, sekretów i zbędnych szczegółów.
ID żądania
Unikalny identyfikator do wyszukania operacji w logach i kontaktu ze wsparciem.
Dodatkowe dane
Dozwolony status, limit, bieżący stan lub bezpieczna przyczyna odmowy.
Można ponowić
Jednoznaczny znacznik błędu tymczasowego, który nie znosi ochrony operacji przed ponownym wykonaniem.
Przerwa przed ponowieniem
Zalecane opóźnienie w sekundach lub nagłówek HTTP dla ograniczenia żądań i czasowej niedostępności.
Błędy pól
Lista problematycznych pól z kodem przyczyny, ścieżką do wartości i bezpiecznym wyjaśnieniem.
Link do dokumentacji
Stały link lub identyfikator sekcji z opisem przyczyny i sposobem naprawy.
Kategorie błędów
Główne kategorie błędów
Status HTTP wskazuje ogólną klasę wyniku, a kod wewnętrzny precyzuje konkretną przyczynę i dozwolone działanie.
Błąd danych wejściowych
Nieprawidłowy format, brak wymaganego pola, nieobsługiwana wartość, nieprawidłowa precyzja kwoty lub błędna struktura żądania.
Błąd uwierzytelniania
Brakujący, wygasły lub nieprawidłowy token, klucz API, podpis, czas żądania lub identyfikator jednorazowy.
Brak wystarczających uprawnień
Klient został rozpoznany, ale nie ma wymaganej roli, marki, rynku lub uprawnienia do działania.
Nie znaleziono obiektu
Gracz, płatność, runda, weryfikacja KYC, dostawca lub inny obiekt nie istnieje albo jest niedostępny dla klienta.
Konflikt stanu
Wersja lub stan obiektu uległy zmianie albo identyfikator operacji został już użyty z innymi parametrami.
Naruszenie reguły biznesowej
Niewystarczające saldo, przekroczony limit, zablokowany gracz, niedozwolony rynek lub niedozwolona zmiana statusu.
Zbyt wiele żądań
Przekroczono dozwoloną liczbę żądań dla klienta, metody, roli lub operacji krytycznej.
Dostawca jest niedostępny
Usługa zewnętrzna jest niedostępna, odpowiada z opóźnieniem lub tymczasowo nie przyjmuje operacji.
Błąd wewnętrzny
Nieoczekiwany błąd platformy bez ujawniania szczegółów wewnętrznych, ale z identyfikatorem do diagnostyki.
Ponowienie i odzyskiwanie
Ponowienie żądania i nieznany wynik
Ponowienie jest bezpieczne dopiero po określeniu typu błędu i sprawdzeniu, czy pierwotna operacja mogła już zostać wykonana.
01
Sprawdzić, czy ponowienie jest dozwolone
Błędy danych, uprawnień i reguł biznesowych zwykle wymagają poprawienia żądania, a nie jego ponownego wysłania.
02
Zachować ten sam klucz operacji
Ponowienie operacji finansowej, gamingowej lub innej operacji krytycznej nie powinno tworzyć nowego wyniku.
03
Zwiększać odstęp między próbami
Odstępy stopniowo rosną, uwzględniają czas wskazany przez serwer i ograniczają łączną liczbę prób.
04
Zatrzymać i przekazać do weryfikacji
Po wyczerpaniu prób operacja jest oznaczana jako niedokończona i przekazywana do ręcznej weryfikacji lub uzgodnienia.
Brak odpowiedzi nie oznacza odrzucenia operacji
Po zerwaniu połączenia po wysłaniu żądania wynik może pozostać nieznany. Przed ponowieniem trzeba sprawdzić stan według identyfikatora operacji lub poczekać na zaufane powiadomienie.
Diagnostyka i kontrola
Logi, identyfikatory, metryki i powiadomienia
Diagnostyka powinna odtwarzać ścieżkę żądania między platformą, adapterem i zewnętrznym dostawcą bez przechowywania zbędnych danych wrażliwych.
Kontekst do analizy
Identyfikatory żądania, korelacji, operacji i zewnętrznego dostawcy.
Adres metody, metoda HTTP, środowisko, klient, czas i długość odpowiedzi.
Status HTTP, kod błędu, liczba prób i stan końcowy.
Zamaskowane pola wrażliwe, bezpieczne nagłówki i wynik weryfikacji podpisu.
Kontrola i powiadomienia
Odsetek błędów według metody, dostawcy, klienta i kategorii przyczyny.
Wzrost liczby długich odpowiedzi, HTTP 5xx, nieprawidłowych podpisów i ograniczeń częstotliwości.
Liczba ponowień, operacji z nieznanym wynikiem i zadań odzyskiwania.
Powiadomienia z progami, osobami odpowiedzialnymi i zasadami eskalacji problemu.
Testowanie
Co sprawdzić w środowisku testowym
Środowisko testowe powinno odtwarzać każdą istotną kategorię błędu i potwierdzać prawidłowe zachowanie klienta, ponowień i kontroli.
Błędy danych wejściowych
Pominięte pola, nieprawidłowe typy, nieobsługiwane wartości, precyzja kwoty i kilka błędów jednocześnie.
Dostęp i uprawnienia
Nieprawidłowy klucz, wygasły token, błędny podpis, niewłaściwa rola, niedozwolony IP i ponownie użyty identyfikator jednorazowy.
Brak odpowiedzi i nieznany wynik
Zerwanie połączenia przed wysłaniem, po przyjęciu operacji i podczas odbierania odpowiedzi końcowej.
Ograniczenie częstotliwości
HTTP 429, zalecana przerwa, żądania równoległe i odzyskanie działania po zakończeniu ograniczenia.
Błędy dostawcy
Niedostępność, prace techniczne, nieprawidłowa odpowiedź, opóźnione powiadomienie i sprzeczny status.
Ponowienie i bezpieczne zatrzymanie
Ograniczenie liczby prób, zwiększanie przerw, czasowe wstrzymanie żądań, kontrolowane odzyskiwanie i ręczna eskalacja problemu.
Lista kontrolna przed uruchomieniem
Integracja produkcyjna jest uruchamiana po sprawdzeniu struktury błędów, zachowania klienta, ochrony przed duplikatami i diagnostyki.
Wszystkie błędy zwracają stabilny kod przyczyny i identyfikator żądania.
Szczegóły błędów nie ujawniają sekretów ani implementacji wewnętrznej.
Tymczasowe i trwałe kategorie błędów są opisane w dokumentacji.
Ponowienie operacji krytycznej wykorzystuje ten sam klucz ochrony przed duplikatami.
Nieznany wynik jest obsługiwany przez sprawdzenie stanu lub zaufane powiadomienie.
Skonfigurowano logi, metryki, powiadomienia, kolejkę odzyskiwania i zasady eskalacji problemu.
Chcesz ujednolicić format błędów API?
Przekaż aktualne odpowiedzi HTTP, kody błędów, zasady ponawiania i problematyczne scenariusze. APIACE pomoże określić wspólny model błędów, bezpieczne odzyskiwanie i kontrolę.