Błędy

Każde nieudane żądanie Bird API zwraca tę samą odpowiedź z błędem JSON, zagnieżdżoną pod kluczem najwyższego poziomu error. Oto rzeczywista odpowiedź na żądanie wysyłki z pustym ciałem:

Przykład kodu

{
  "error": {
    "type": "validation_error",
    "code": "E01001",
    "name": "ValidationError",
    "message": "Request has 1 validation error.",
    "doc_url": "https://bird.com/docs/api/errors/E01001",
    "request_id": "req_01ky7q3hckecgv6d7jpq865532",
    "details": [{ "param": "body", "message": "missing properties 'from', 'to'" }]
  }
}

Status HTTP wynika z type. Błędy klienta używają 400 dla źle sformułowanych żądań, 401 lub 403 dla problemów z dostępem, 402 dla rozliczeń i 404 dla brakujących zasobów. Używają 409 dla konfliktów, 412 dla niespełnionych warunków wstępnych, 422 dla błędów walidacji i reguł biznesowych oraz 429 dla ograniczania liczby żądań. Błędy po stronie Bird używają 5xx. Status wskazuje kategorię; odpowiedź z błędem wyjaśnia, co się stało.

Pola odpowiedzi z błędem

Pole	Rola
type	Ogólna kategoria do rozgałęziania: validation_error, auth_error, permission_error, not_found_error, conflict_error, rate_limit_error, billing_error, internal_error i kilka innych. Zamknięty enum, który rozrasta się rzadko.
code	Nieprzezroczysty, stabilny identyfikator (E01001). Kanoniczne odniesienie: unikalny, nigdy nie jest zmieniany ani ponownie używany. Gdy błąd zostaje wycofany, jego kod jest trwale zarezerwowany.
name	Czytelny slug (ValidationError) ułatwiający czytanie logów. Zawsze w parze z code, nigdy jako jego zamiennik.
message	Czytelny opis. Niestabilny: treść może się zmienić bez zapowiedzi. Wyświetlaj go, loguj, nigdy nie parsuj.
param	Dla błędów związanych z danymi wejściowymi, pole, które je wywołało. Pomijane, gdy nie dotyczy.
doc_url	Stabilny link do strony dokumentacji dla tego kodu.
request_id	Zawsze obecny; zwracany również jako nagłówek odpowiedzi X-Request-Id. Podawaj go w zgłoszeniach do wsparcia; pozwala Bird prześledzić dokładne żądanie.
details	Problemy walidacji na poziomie pól. Obecne tylko w odpowiedziach validation_error.
remediation	Czytelny następny krok do rozwiązania błędu. Obecny, gdy sposób naprawy jest znany.
next	Operacje naprawcze w kolejności, w jakiej należy je wykonać. Obecne dla błędów ze ściśle określoną procedurą naprawczą, np. niespełnionych warunków wstępnych.
vendor_code	Dosłowny kod z systemu zewnętrznego (kod odpowiedzi SMTP, kod odrzucenia płatności). Obecny tylko wtedy, gdy Bird przekazuje kod systemu zewnętrznego, na który możesz chcieć zareagować.

Rozgałęziaj na podstawie type do obsługi ogólnej i code do obsługi szczegółowej, nigdy na podstawie message. Typowy klient przełącza się na type (ponawia przy rate_limit_error, pokazuje validation_error użytkownikowi, alarmuje kogoś przy internal_error) i dopasowuje poszczególne wartości code tylko dla kilku błędów, które obsługuje specjalnie.

Kody takie jak E04012 są celowo nieprzezroczyste. Każdy kod prowadzi do strony dokumentacji przez doc_url, która wyjaśnia przyczynę i sposób rozwiązania. Pełny katalog znajduje się w dokumentacji błędów.

Błędy walidacji: jeden kod, wiele szczegółów

Walidacja na poziomie pól nie otrzymuje osobnego kodu dla każdej kombinacji pola i błędu. Każdy błąd walidacji to E01001 ValidationError z tablicą details wymieniającą każdy problem na poziomie pola jako {param, message}, tak jak przechwycony błąd wysyłki wymienia brakujące właściwości. Ciągi message wewnątrz details mogą się zmieniać i powinny być wyłącznie wyświetlane. Używaj param, aby mapować problemy na pola formularza.

Wskazówki naprawcze: remedium i następne kroki

Błędy ze znanym rozwiązaniem zawierają je w odpowiedzi z błędem. Oto rzeczywista odpowiedź na wywołanie webhooków z kluczem API, któremu brakuje wymaganego zakresu:

Przykład kodu

{
  "error": {
    "type": "permission_error",
    "code": "E02035",
    "name": "InsufficientScope",
    "message": "This request requires the \"webhooks:read\" scope, which your credential has not been granted.",
    "param": "webhooks:read",
    "doc_url": "https://bird.com/docs/api/errors/E02035",
    "request_id": "req_01ky7q4665emc9tw1pxkptaqwq",
    "remediation": "Re-authenticate with a credential that has been granted the required scope, then retry."
  }
}

remediation to zdanie dla człowieka lub logu agenta; next, jeśli jest obecny, wymienia operacje API naprawiające błąd w kolejności do wykonania (zweryfikuj domenę, potem ponów wysyłkę). Agenci i narzędzia CLI mogą wykonywać next bezpośrednio; klienty interaktywne mogą wyświetlać remediation w niezmienionej formie.

Prawidłowa obsługa błędów

Ponawiaj 429 i 5xx, domyślnie nic więcej. Respektuj Retry-After przy ograniczaniu liczby żądań (zobacz Ograniczanie liczby żądań), używaj wykładniczego wycofywania przy 5xx i wysyłaj Idempotency-Key, aby ponowienia żądań modyfikujących były bezpieczne.
Loguj code, name i request_id razem. Kod to wartość, której będziesz szukać w dokumentacji i własnych logach; identyfikator żądania to informacja potrzebna wsparciu.
Toleruj nowe kody i typy. Nowe kody błędów pojawiają się regularnie w miarę rozwoju produktów, a enum type od czasu do czasu zyskuje nową wartość. Pisz handler z rozsądną domyślną gałęzią zamiast wyczerpującego dopasowania.

Następne kroki

Dokumentacja błędów: pełny katalog błędów, jedna strona na kod
Idempotentność: bezpieczne ponawianie żądań modyfikujących
Ograniczanie liczby żądań: nagłówki limitów i wskazówki dotyczące wycofywania

Powiązane zasoby

Kontynuuj z dokumentacją, przewodnikami i przykładami dotyczącymi tego tematu. Zasoby są w języku angielskim.

Zrozum koncepcjęShould I use a Bird SDK or call the API directly?Podążaj ścieżką naukiBuild your first integration Przewodnik wdrożeniowySend your first email

Uzyskaj brief wdrożeniowy