Sign inGet Started

Odpowiedzi z błędem

Każde nieudane żądanie zwraca tę samą kopertę JSON pod kluczem najwyższego poziomu error, ze statusem HTTP, który wskazuje ogólną kategorię. Ta strona opisuje kontrakt; wskazówki dotyczące rozgałęziania, ponownych prób i filozofii katalogu kodów znajdziesz w sekcji Błędy.
Przykład kodu
{
  "error": {
    "type": "validation_error",
    "code": "E01001",
    "name": "ValidationError",
    "message": "Request validation failed.",
    "doc_url": "https://bird.com/docs/api/errors/E01001",
    "request_id": "req_01krdgeqcxet5s7t44vh8rt9mg",
    "details": [
      { "param": "contact_id", "message": "this field is reserved and not yet supported" },
      { "param": "topic_id", "message": "this field is reserved and not yet supported" }
    ]
  }
}

Pola koperty

PoleZawsze obecneOpis
typeTakOgólna kategoria do rozgałęziania: zamknięty enum (auth_error, validation_error, rate_limit_error, ...).
codeTakNieprzezroczysty, stabilny identyfikator odpowiadający E\d{5}. Unikalny, nigdy nie jest zmieniany ani ponownie używany; kanoniczny element do dopasowywania.
nameTakCzytelny slug (ValidationError) ułatwiający czytanie logów. Zawsze w parze z code, nigdy jako jego zamiennik.
messageTakCzytelny opis. Niestabilny; wyświetlaj go lub loguj, nigdy go nie parsuj.
doc_urlTakStabilny link do strony dokumentacji tego code.
request_idTakIdentyfikator korelacji, zwracany również jako nagłówek odpowiedzi X-Request-Id. Podawaj go w zgłoszeniach do wsparcia.
paramNiePole powodujące błąd, gdy winne jest jedno pole.
detailsNieBłędy walidacji poszczególnych pól jako obiekty {param, message}, gdzie param to ścieżka z kropkami, np. to[0].email. Obecne tylko w odpowiedziach validation_error.
vendor_codeNieDosłowny kod z systemu niższego poziomu (kod odpowiedzi SMTP, kod odrzucenia płatności), gdy warto na niego zareagować.

Mapowanie statusów HTTP

Każdy type odpowiada dokładnie jednemu statusowi HTTP, więc status i koperta nigdy nie są ze sobą sprzeczne.
StatustypeZnaczenie
400bad_request_errorŻądanie było zniekształcone: ciało niemożliwe do sparsowania lub nieprawidłowy nagłówek (na przykład nieprawidłowy Idempotency-Key).
401auth_errorŻądanie zawierało brakujące, nieprawidłowe lub unieważnione dane uwierzytelniające. Zobacz Uwierzytelnianie.
402billing_errorŻądanie wymaga metody płatności, salda lub planu, którego organizacja nie posiada. Zobacz Płatności i użycie.
403permission_errorDane uwierzytelniające są prawidłowe, ale nie mają uprawnień do wykonania tego żądania. Zobacz Uwierzytelnianie.
404not_found_errorŻadna trasa nie pasuje do tej ścieżki lub zasób nie istnieje w tym obszarze roboczym. Zobacz Regiony.
409conflict_errorŻądanie koliduje z bieżącym stanem zasobu, w tym konflikty idempotentności (E01004, E01005). Zobacz Idempotentność.
410gone_errorZasób istniał, ale został trwale usunięty.
412precondition_errorWarunek wstępny dla tego żądania nie został spełniony.
413payload_too_large_errorCiało żądania przekracza maksymalny dozwolony rozmiar.
421misdirected_errorŻądanie dotarło do regionu, który nie może go obsłużyć. Zobacz Regiony.
422delivery_errorWiadomość została przyjęta jako żądanie, ale nie może zostać dostarczona pod wskazany adres.
422validation_errorCiało żądania zostało sparsowane, ale co najmniej jedna wartość jest nieprawidłowa.
425too_early_errorŻądanie dotarło wcześniej, niż może zostać przetworzone.
429rate_limit_errorGrupa limitów została wyczerpana dla tego obszaru roboczego. Zobacz Limity żądań.
499client_closed_request_errorPołączenie zostało zamknięte, zanim odpowiedź była gotowa, zwykle dlatego, że wywołujący przestał czekać.
500internal_errorCoś po naszej stronie nie powiodło się podczas przetwarzania żądania. Zobacz Idempotentność.
501not_implemented_errorEndpoint jest zadeklarowany w API, ale nie został jeszcze zaimplementowany.
503service_unavailable_errorZasób, od którego zależy to żądanie, jest tymczasowo niedostępny.

Obsługa błędów w SDK

Każdy SDK mapuje kopertę na natywny model błędów danego języka i udostępnia wszystkie pola koperty (type, code, message, doc_url, request_id, ...) na obiekcie błędu.
import { BirdRateLimitError, BirdValidationError, BirdAPIError } from "@messagebird/sdk";

try {
  await bird.email.send({
    from: { email: "onboarding@messagebird.dev", name: "Bird" },
    to: ["delivered@messagebird.dev"],
    subject: "Hello from Bird",
    html: "<p>My first Bird email.</p>",
  });
} catch (err) {
  if (err instanceof BirdRateLimitError) console.log(`rate limited; retry in ${err.retryAfter}s`);
  else if (err instanceof BirdValidationError) console.error(err.details);
  else if (err instanceof BirdAPIError) console.error(err.code, err.requestId);
  else throw err;
}

Katalog błędów

Wszystkie kody błędów zwracane przez publiczne Bird API, podzielone na jedną stronę na zakres kodów. Każda strona zakresu wymienia swoje kody, a każdy kod ma własną stronę z przyczyną i zalecanym działaniem. Pole doc_url w każdej odpowiedzi z błędem prowadzi bezpośrednio do strony danego kodu.
ZakresObszarKody
E01xxxInfrastruktura30 kodów, 2 wycofane
E02xxxUwierzytelnianie i tożsamość9 kodów, 2 wycofane
E03xxxPłatności i plany12 kodów
E04xxxWysyłka i dostarczanie e-maili67 kodów, 3 wycofane
E05xxxDomeny i DNS19 kodów
E06xxxWebhooki7 kodów
E07xxxPortfel4 kody
E10xxxLimity9 kodów, 2 wycofane
E11xxxPule IP i dedykowane adresy IP4 kody, 1 wycofany
E12xxxWysyłka i dostarczanie SMS49 kodów, 5 wycofanych
E13xxxVerify7 kodów, 1 wycofany
E14xxxNumery5 kodów
E15xxxWysyłka i dostarczanie WhatsApp49 kodów
E16xxxTrust1 kod
E17xxxSkrzynki agentów14 kodów, 2 wycofane
E19xxxZgodność rejestracji4 kody
E21xxxGłos i trunking SIP16 kodów, 7 wycofanych
E22xxxWyszukiwanie numerów4 kody
E23xxxRealtime1 kod
E24xxxCompetitive Insights6 kodów
E25xxxSendability5 kodów, 1 wycofany
E27xxxInbox Insights5 kodów
E28xxxApple Messages for Business18 kodów, 2 wycofane
E32xxxPotwierdzanie operacji6 kodów

Powiązane

Powiązane zasoby

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

Uzyskaj brief wdrożeniowy