Nigdy nie ponawiaj
invalid_request, invalid_amount, unknown_asset_or_rail, asset_not_offered, unauthorized. Wina leży po stronie żądania: ponowienie go bez zmian da ten sam wynik. Popraw je lub wyświetl powód.
Developers
Katalog błędów
Każdy błąd niesie stabilny, czytelny maszynowo kod i spójny status HTTP. Kod jest tym, na czym powinna opierać się Twoja integracja: tekst może ewoluować, kod nie.
Kształt błędu
Obecny kształt jest celowo minimalny. Jest stabilny i to się liczy: kod i nic, co ujawniałoby wewnętrzny szczegół.
{ "error": "rate_stale" }{
"error": "rail_not_open",
"reason": {
"fr": "La retenue TDS de 1 % et l’enregistrement FIU-IND exigent une entite locale…",
"en": "The 1% TDS withholding and FIU-IND registration require a local entity…"
}
}Niektóre błędy niosą dwujęzyczny obiekt powodu, przeznaczony do pokazania użytkownikowi bez zmian. Zamknięty kanał płatności jest jednym z nich: powód wyjaśnia nazwane ograniczenie regulacyjne, a nie awarię, a jego pokazanie oszczędza zgłoszenie do wsparcia. Wersjonowane API doda identyfikator żądania do tej koperty, abyś mógł wskazać nam dokładną linię w naszych logach.
Obowiązujące kody
Te kody są dziś zwracane przez punkt końcowy wyceny.
| code | HTTP | Co to oznacza | Co robić |
|---|---|---|---|
invalid_request | 400 | Treść żądania nie przechodzi walidacji schematu: brakujące pole, zły typ, wartość poza dozwolonymi granicami. | Sprawdź, czy kwota jest ciągiem znaków, a nie liczbą, oraz czy kierunek to dokładnie „sell” lub „receive”. |
invalid_amount | 400 | Kwota nie może zostać sparsowana lub ma więcej miejsc po przecinku, niż akceptuje aktywo lub waluta. | Zaokrąglij do precyzji jednostki: 6 miejsc po przecinku dla USDT, 8 dla BTC, 2 dla euro, 0 dla franka CFA. |
unknown_asset_or_rail | 404 | Identyfikator aktywa lub kanału nie istnieje w katalogu. | Identyfikatory są stabilne i nigdy nie są ponownie przypisywane. Załaduj ponownie katalog, zamiast zgadywać. |
rail_not_open | 409 | Kanał istnieje, ale nie jest otwarty. Odpowiedź zawiera dokładny powód, w obu językach. | Pokaż powód bez zmian: wyjaśnia ograniczenie regulacyjne, a nie awarię. Zaproponuj otwarty kanał w tym samym kraju. |
asset_not_offered | 409 | Aktywo jest w katalogu, ale nie jest oferowane — przypadek aktywów o zwiększonej anonimowości. | Nie oferuj go w swoim selektorze. Katalog zwraca je z powodem, abyś mógł to wyjaśnić. |
rate_stale | 503 | Ostatnia znana cena przekracza maksymalny dozwolony wiek. Silnik odmawia wyceny zamiast podawać nieaktualną cenę jako wiążącą. | Ponów próbę po kilku sekundach. Nie buforuj ostatniej udanej wyceny, aby wypełnić lukę: to byłby dokładnie błąd, któremu ten kod zapobiega. |
rate_unavailable | 503 | Brak dostępnej ceny dla tej pary aktywo / waluta. | Wyłącz parę w swoim interfejsie, zamiast pokazywać szacunek. Wyświetlony szacunek staje się oczekiwaniem. |
quote_failed | 500 | Nieoczekiwany błąd podczas obliczeń. Nie jest zwracana żadna wycena. | Ponów próbę raz; jeśli błąd się powtórzy, napisz do nas z dokładnym znacznikiem czasu wywołania. |
Kody z opublikowanego kontraktu
Te kody towarzyszą punktom końcowym, które nie są jeszcze otwarte. Są opublikowane, aby obsługa błędów została napisana raz.
| code | HTTP | Co to oznacza | Co robić |
|---|---|---|---|
unauthorized | 401 | Brak klucza, klucz odwołany lub użyty w niewłaściwym środowisku. | Klucz sk_test_ nie działa w środowisku produkcyjnym i odwrotnie również nie działa: to celowe. |
idempotency_conflict | 409 | Ten sam klucz idempotencji został już użyty z innym ciałem żądania. | Klucz należy do jednego zamiaru. Jeśli treść się zmienia, klucz się zmienia; w przeciwnym razie nie wiadomo, które z dwóch zamówień należy powtórzyć. |
quote_expired | 409 | Kurs wygasł poza oknem blokady. | Poproś o nowy kurs i zaakceptuj nową kwotę. Nigdy nie zmieniamy ceny po cichu wobec klienta. |
beneficiary_rejected | 422 | Dane beneficjenta nie przechodzą walidacji systemu płatności: nieprawidłowa suma kontrolna, niezgodny format lub nazwa niezgodna ze zweryfikowaną tożsamością. | Odpowiedź wskazuje pole, którego dotyczy problem. Nazwa beneficjenta musi być zweryfikowaną tożsamością: wypłata na rzecz osoby trzeciej nie jest możliwa. |
country_not_served | 451 | Kraj docelowy nie jest obsługiwany: sankcje, środki ograniczające lub brak lokalnych ram prawnych. | Kod 451 jest wybierany celowo zamiast 404: gdy odmawiamy, mówimy, że to odmowa i dlaczego. |
rate_limited | 429 | Zbyt wiele wywołań w ruchomym oknie czasowym. | Szanuj nagłówek Retry-After. Wyceny są tanie w kolejce, drogie w nadużywaniu. |
not_found | 404 | Zasób nie istnieje lub nie należy do Twojego klucza. | Oba przypadki zwracają ten sam kod: odpowiedź, która je rozróżnia, pozwoliłaby każdemu na wyliczenie cudzych referencji. |
Co nie jest błędem
Kwota poza granicami kanału zwraca ważną wycenę z obiektem limitError. To nie jest błąd: to informacja, którą Twój interfejs powinien wyświetlić.
"limitError": { "code": "below_min", "limit": "20.00" }Traktowanie tego przypadku jako błędu HTTP pozbawiłoby Cię obliczonej kwoty, a tym samym możliwości powiedzenia użytkownikowi: „brakuje Ci 16,53 EUR do minimum dla tej metody wypłaty”. Limit dotyczy kwoty netto, tej, którą otrzymuje beneficjent.
Ponawiać czy nie
Trzy rodziny, trzy zachowania. Ponawianie błędu walidacji w pętli tylko zapycha logi.
Ponawiaj z backoffem
rate_stale, rate_unavailable, quote_failed oraz wszelkie ograniczanie szybkości. Odczekaj kilka sekund, zwiększając odstępy między próbami. Nie wypełniaj odstępu buforowaną wyceną.
Poproś o decyzję
rail_not_open, quote_expired, beneficiary_rejected, country_not_served. Sytuacja wymaga ludzkiego wyboru: zaproponuj inny kanał, świeżą wycenę, poprawione dane.