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
| Pole | Zawsze obecne | Opis |
|---|---|---|
| type | Tak | Ogólna kategoria do rozgałęziania: zamknięty enum (auth_error, validation_error, rate_limit_error, ...). |
| code | Tak | Nieprzezroczysty, stabilny identyfikator odpowiadający E\d{5}. Unikalny, nigdy nie jest zmieniany ani ponownie używany; kanoniczny element do dopasowywania. |
| name | Tak | Czytelny slug (ValidationError) ułatwiający czytanie logów. Zawsze w parze z code, nigdy jako jego zamiennik. |
| message | Tak | Czytelny opis. Niestabilny; wyświetlaj go lub loguj, nigdy go nie parsuj. |
| doc_url | Tak | Stabilny link do strony dokumentacji tego code. |
| request_id | Tak | Identyfikator korelacji, zwracany również jako nagłówek odpowiedzi X-Request-Id. Podawaj go w zgłoszeniach do wsparcia. |
| param | Nie | Pole powodujące błąd, gdy winne jest jedno pole. |
| details | Nie | Błę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_code | Nie | Dosł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.
| Status | type | Znaczenie |
|---|---|---|
| 400 | bad_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). |
| 401 | auth_error | Żądanie zawierało brakujące, nieprawidłowe lub unieważnione dane uwierzytelniające. Zobacz Uwierzytelnianie. |
| 402 | billing_error | Żądanie wymaga metody płatności, salda lub planu, którego organizacja nie posiada. Zobacz Płatności i użycie. |
| 403 | permission_error | Dane uwierzytelniające są prawidłowe, ale nie mają uprawnień do wykonania tego żądania. Zobacz Uwierzytelnianie. |
| 404 | not_found_error | Żadna trasa nie pasuje do tej ścieżki lub zasób nie istnieje w tym obszarze roboczym. Zobacz Regiony. |
| 409 | conflict_error | Żądanie koliduje z bieżącym stanem zasobu, w tym konflikty idempotentności (E01004, E01005). Zobacz Idempotentność. |
| 410 | gone_error | Zasób istniał, ale został trwale usunięty. |
| 412 | precondition_error | Warunek wstępny dla tego żądania nie został spełniony. |
| 413 | payload_too_large_error | Ciało żądania przekracza maksymalny dozwolony rozmiar. |
| 421 | misdirected_error | Żądanie dotarło do regionu, który nie może go obsłużyć. Zobacz Regiony. |
| 422 | delivery_error | Wiadomość została przyjęta jako żądanie, ale nie może zostać dostarczona pod wskazany adres. |
| 422 | validation_error | Ciało żądania zostało sparsowane, ale co najmniej jedna wartość jest nieprawidłowa. |
| 425 | too_early_error | Żądanie dotarło wcześniej, niż może zostać przetworzone. |
| 429 | rate_limit_error | Grupa limitów została wyczerpana dla tego obszaru roboczego. Zobacz Limity żądań. |
| 499 | client_closed_request_error | Połączenie zostało zamknięte, zanim odpowiedź była gotowa, zwykle dlatego, że wywołujący przestał czekać. |
| 500 | internal_error | Coś po naszej stronie nie powiodło się podczas przetwarzania żądania. Zobacz Idempotentność. |
| 501 | not_implemented_error | Endpoint jest zadeklarowany w API, ale nie został jeszcze zaimplementowany. |
| 503 | service_unavailable_error | Zasó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;
}from bird import APIStatusError, RateLimitError, ValidationError
try:
client.email.send(
from_={"email": "onboarding@messagebird.dev", "name": "Bird"},
to=["delivered@messagebird.dev"],
subject="Hello from Bird",
text="My first Bird email.",
)
except RateLimitError as err:
print("rate limited; retry after", err.retry_after)
except ValidationError as err:
print(err.status_code, err.details)
except APIStatusError as err:
print(err.status_code, err.code, err.request_id)if err != nil {
var rle *bird.RateLimitError
var ve *bird.ValidationError
var ae *bird.APIError
switch {
case errors.As(err, &rle):
fmt.Println("rate limited; retry after", rle.RetryAfter)
case errors.As(err, &ve):
for _, d := range ve.Details {
fmt.Printf("%s: %s\n", d.Param, d.Message)
}
case errors.As(err, &ae):
fmt.Printf("API error %s (status %d, request %s)\n", ae.Code, ae.StatusCode, ae.RequestID)
default:
log.Print(err) // transport: *bird.ConnectionError or *bird.TimeoutError
}
}try {
$bird->email->send(
from: 'Bird <onboarding@messagebird.dev>',
to: ['delivered@messagebird.dev'],
subject: 'Hello from Bird',
html: '<p>My first Bird email.</p>',
);
} catch (ApiException $e) {
// The server returned an error response. $status is the HTTP status, $type
// the coarse category, $errorCode the stable E##### code.
echo $e->status, ' ', $e->errorCode ?? $e->type ?? 'error';
} catch (ConnectionException $e) {
// All retry attempts failed, so no HTTP response is available.
echo 'transport error: ', $e->getMessage();
}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.
| Zakres | Obszar | Kody |
|---|---|---|
| E01xxx | Infrastruktura | 30 kodów, 2 wycofane |
| E02xxx | Uwierzytelnianie i tożsamość | 9 kodów, 2 wycofane |
| E03xxx | Płatności i plany | 12 kodów |
| E04xxx | Wysyłka i dostarczanie e-maili | 67 kodów, 3 wycofane |
| E05xxx | Domeny i DNS | 19 kodów |
| E06xxx | Webhooki | 7 kodów |
| E07xxx | Portfel | 4 kody |
| E10xxx | Limity | 9 kodów, 2 wycofane |
| E11xxx | Pule IP i dedykowane adresy IP | 4 kody, 1 wycofany |
| E12xxx | Wysyłka i dostarczanie SMS | 49 kodów, 5 wycofanych |
| E13xxx | Verify | 7 kodów, 1 wycofany |
| E14xxx | Numery | 5 kodów |
| E15xxx | Wysyłka i dostarczanie WhatsApp | 49 kodów |
| E16xxx | Trust | 1 kod |
| E17xxx | Skrzynki agentów | 14 kodów, 2 wycofane |
| E19xxx | Zgodność rejestracji | 4 kody |
| E21xxx | Głos i trunking SIP | 16 kodów, 7 wycofanych |
| E22xxx | Wyszukiwanie numerów | 4 kody |
| E23xxx | Realtime | 1 kod |
| E24xxx | Competitive Insights | 6 kodów |
| E25xxx | Sendability | 5 kodów, 1 wycofany |
| E27xxx | Inbox Insights | 5 kodów |
| E28xxx | Apple Messages for Business | 18 kodów, 2 wycofane |
| E32xxx | Potwierdzanie operacji | 6 kodów |
Powiązane
- Koncepcje błędów: strategia rozgałęziania, szczegóły walidacji i semantyka vendor_code
- Uwierzytelnianie: dane uwierzytelniające za 401 i 403
- Nagłówek Idempotency-Key: błędy konfliktu 409 i bezpieczne ponowne próby
- Limity żądań: zasady, nagłówki i obsługa 429
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 integrationPrzewodnik wdrożeniowySend your first email
Uzyskaj brief wdrożeniowy