Respons kesalahan
Setiap permintaan yang gagal mengembalikan envelope JSON yang sama di bawah key level atas error, dengan status HTTP yang menunjukkan kategori umumnya. Halaman ini adalah kontrak wire; untuk panduan tentang branching, coba lagi, dan filosofi katalog kode, lihat Errors.
Contoh kode
{
"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" }
]
}
}Field envelope
| Field | Selalu ada | Deskripsi |
|---|---|---|
| type | Ya | Kategori umum untuk branching kasar: enum tertutup (auth_error, validation_error, rate_limit_error, ...). |
| code | Ya | Identifier opaque dan stabil yang cocok dengan E\d{5}. Unik, tidak pernah diganti nama, tidak pernah digunakan ulang; acuan kanonik untuk pencocokan. |
| name | Ya | Slug yang mudah dibaca (ValidationError) untuk keterbacaan log. Selalu dipasangkan dengan code, bukan pengganti untuk itu. |
| message | Ya | Deskripsi yang mudah dibaca. Tidak stabil; tampilkan atau catat di log, jangan pernah parsing. |
| doc_url | Ya | Tautan stabil ke halaman dokumentasi untuk code ini. |
| request_id | Ya | Correlation ID, juga dikembalikan sebagai header respons X-Request-Id. Sertakan dalam permintaan dukungan. |
| param | Tidak | Field yang bermasalah, ketika satu field menjadi penyebab. |
| details | Tidak | Kegagalan validasi per field sebagai objek {param, message}, di mana param adalah path bertitik seperti to[0].email. Hanya ada pada respons validation_error. |
| vendor_code | Tidak | Kode verbatim dari sistem hilir (kode balasan SMTP, kode penolakan pembayaran) ketika layak ditindaklanjuti. |
Pemetaan status HTTP
Setiap type dipetakan ke tepat satu status HTTP, sehingga status dan envelope tidak pernah bertentangan.
| Status | type | Arti |
|---|---|---|
| 400 | bad_request_error | Permintaan tidak valid: body yang tidak dapat di-parse atau header yang tidak valid (misalnya, Idempotency-Key yang salah). |
| 401 | auth_error | Permintaan membawa kredensial yang hilang, tidak valid, atau dicabut. Lihat Autentikasi. |
| 402 | billing_error | Permintaan memerlukan metode pembayaran, saldo, atau paket yang tidak dimiliki organisasi. Lihat Billing dan penggunaan. |
| 403 | permission_error | Kredensial valid, tetapi tidak diizinkan untuk melakukan permintaan ini. Lihat Autentikasi. |
| 404 | not_found_error | Tidak ada rute yang cocok dengan path ini, atau resource tidak ada di workspace ini. Lihat Region. |
| 409 | conflict_error | Permintaan berkonflik dengan kondisi resource saat ini, termasuk konflik idempotensi (E01004, E01005). Lihat Idempotensi. |
| 410 | gone_error | Resource pernah ada tetapi telah dihapus secara permanen. |
| 412 | precondition_error | Prasyarat untuk permintaan ini tidak terpenuhi. |
| 413 | payload_too_large_error | Body permintaan melebihi ukuran maksimum yang diizinkan. |
| 421 | misdirected_error | Permintaan mencapai region yang tidak dapat melayaninya. Lihat Region. |
| 422 | delivery_error | Pesan diterima sebagai permintaan tetapi tidak dapat dikirim sesuai alamat tujuan. |
| 422 | validation_error | Body permintaan berhasil di-parse, tetapi satu atau beberapa nilai tidak valid. |
| 425 | too_early_error | Permintaan tiba lebih awal dari waktu pemrosesan yang diizinkan. |
| 429 | rate_limit_error | Grup pembatasan laju permintaan telah habis untuk workspace ini. Lihat Pembatasan laju permintaan. |
| 499 | client_closed_request_error | Koneksi tertutup sebelum respons siap, biasanya karena pemanggil berhenti menunggu. |
| 500 | internal_error | Terjadi kegagalan di sisi kami saat memproses permintaan. Lihat Idempotensi. |
| 501 | not_implemented_error | Endpoint dideklarasikan dalam API tetapi belum diimplementasikan. |
| 503 | service_unavailable_error | Sesuatu yang dibutuhkan permintaan ini sedang tidak tersedia untuk sementara. |
Menangani kesalahan di SDK
Setiap SDK memetakan envelope ke model error native bahasanya dan membawa setiap field envelope (type, code, message, doc_url, request_id, ...) pada nilai error.
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 error
Semua kode error yang dikembalikan oleh Bird API publik, dibagi menjadi satu halaman per rentang kode. Setiap halaman rentang mencantumkan kodenya, dan setiap kode memiliki halamannya sendiri dengan penyebab dan tindakan yang harus dilakukan. doc_url pada setiap respons kesalahan menautkan langsung ke halaman kode tersebut.
| Rentang | Area | Kode |
|---|---|---|
| E01xxx | Infrastruktur | 30 kode, 2 dihentikan |
| E02xxx | Auth & identitas | 9 kode, 2 dihentikan |
| E03xxx | Billing & paket | 12 kode |
| E04xxx | Pengiriman & pengiriman email | 67 kode, 3 dihentikan |
| E05xxx | Domain & DNS | 19 kode |
| E06xxx | Webhook | 7 kode |
| E07xxx | Wallet | 4 kode |
| E10xxx | Kuota | 9 kode, 2 dihentikan |
| E11xxx | IP pool & IP dedicated | 4 kode, 1 pensiun |
| E12xxx | Pengiriman & delivery SMS | 49 kode, 5 dihentikan |
| E13xxx | Verify | 7 kode, 1 pensiun |
| E14xxx | Nomor | 5 kode |
| E15xxx | Pengiriman & delivery WhatsApp | 49 kode |
| E16xxx | Trust | 1 kode |
| E17xxx | Kotak masuk agen | 14 kode, 2 pensiun |
| E19xxx | Kepatuhan registrasi | 4 kode |
| E21xxx | Voice & trunking SIP | 16 kode, 7 dihentikan |
| E22xxx | Number lookup | 4 kode |
| E23xxx | Realtime | 1 kode |
| E24xxx | Competitive Insights | 6 kode |
| E25xxx | Sendability | 5 kode, 1 dihentikan |
| E27xxx | Inbox Insights | 5 kode |
| E28xxx | Apple Messages for Business | 18 kode, 2 dihentikan |
| E32xxx | Konfirmasi operasi | 6 kode |
Terkait
- Konsep Errors: strategi branching, detail validasi, dan semantik vendor_code
- Autentikasi: kredensial di balik 401 dan 403
- Header Idempotency-Key: error konflik 409 dan coba lagi yang aman
- Pembatasan laju permintaan: kebijakan, header, dan penanganan 429
Sumber daya terkait
Lanjutkan dengan dokumentasi, panduan, dan contoh untuk topik ini. Sumber daya tersedia dalam bahasa Inggris.
Pahami konsepnyaShould I use a Bird SDK or call the API directly?Ikuti jalur pembelajaranBuild your first integrationPanduan implementasiSend your first email
Dapatkan ringkasan implementasi