Sign inGet Started

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

FieldSelalu adaDeskripsi
typeYaKategori umum untuk branching kasar: enum tertutup (auth_error, validation_error, rate_limit_error, ...).
codeYaIdentifier opaque dan stabil yang cocok dengan E\d{5}. Unik, tidak pernah diganti nama, tidak pernah digunakan ulang; acuan kanonik untuk pencocokan.
nameYaSlug yang mudah dibaca (ValidationError) untuk keterbacaan log. Selalu dipasangkan dengan code, bukan pengganti untuk itu.
messageYaDeskripsi yang mudah dibaca. Tidak stabil; tampilkan atau catat di log, jangan pernah parsing.
doc_urlYaTautan stabil ke halaman dokumentasi untuk code ini.
request_idYaCorrelation ID, juga dikembalikan sebagai header respons X-Request-Id. Sertakan dalam permintaan dukungan.
paramTidakField yang bermasalah, ketika satu field menjadi penyebab.
detailsTidakKegagalan validasi per field sebagai objek {param, message}, di mana param adalah path bertitik seperti to[0].email. Hanya ada pada respons validation_error.
vendor_codeTidakKode 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.
StatustypeArti
400bad_request_errorPermintaan tidak valid: body yang tidak dapat di-parse atau header yang tidak valid (misalnya, Idempotency-Key yang salah).
401auth_errorPermintaan membawa kredensial yang hilang, tidak valid, atau dicabut. Lihat Autentikasi.
402billing_errorPermintaan memerlukan metode pembayaran, saldo, atau paket yang tidak dimiliki organisasi. Lihat Billing dan penggunaan.
403permission_errorKredensial valid, tetapi tidak diizinkan untuk melakukan permintaan ini. Lihat Autentikasi.
404not_found_errorTidak ada rute yang cocok dengan path ini, atau resource tidak ada di workspace ini. Lihat Region.
409conflict_errorPermintaan berkonflik dengan kondisi resource saat ini, termasuk konflik idempotensi (E01004, E01005). Lihat Idempotensi.
410gone_errorResource pernah ada tetapi telah dihapus secara permanen.
412precondition_errorPrasyarat untuk permintaan ini tidak terpenuhi.
413payload_too_large_errorBody permintaan melebihi ukuran maksimum yang diizinkan.
421misdirected_errorPermintaan mencapai region yang tidak dapat melayaninya. Lihat Region.
422delivery_errorPesan diterima sebagai permintaan tetapi tidak dapat dikirim sesuai alamat tujuan.
422validation_errorBody permintaan berhasil di-parse, tetapi satu atau beberapa nilai tidak valid.
425too_early_errorPermintaan tiba lebih awal dari waktu pemrosesan yang diizinkan.
429rate_limit_errorGrup pembatasan laju permintaan telah habis untuk workspace ini. Lihat Pembatasan laju permintaan.
499client_closed_request_errorKoneksi tertutup sebelum respons siap, biasanya karena pemanggil berhenti menunggu.
500internal_errorTerjadi kegagalan di sisi kami saat memproses permintaan. Lihat Idempotensi.
501not_implemented_errorEndpoint dideklarasikan dalam API tetapi belum diimplementasikan.
503service_unavailable_errorSesuatu 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;
}

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.
RentangAreaKode
E01xxxInfrastruktur30 kode, 2 dihentikan
E02xxxAuth & identitas9 kode, 2 dihentikan
E03xxxBilling & paket12 kode
E04xxxPengiriman & pengiriman email67 kode, 3 dihentikan
E05xxxDomain & DNS19 kode
E06xxxWebhook7 kode
E07xxxWallet4 kode
E10xxxKuota9 kode, 2 dihentikan
E11xxxIP pool & IP dedicated4 kode, 1 pensiun
E12xxxPengiriman & delivery SMS49 kode, 5 dihentikan
E13xxxVerify7 kode, 1 pensiun
E14xxxNomor5 kode
E15xxxPengiriman & delivery WhatsApp49 kode
E16xxxTrust1 kode
E17xxxKotak masuk agen14 kode, 2 pensiun
E19xxxKepatuhan registrasi4 kode
E21xxxVoice & trunking SIP16 kode, 7 dihentikan
E22xxxNumber lookup4 kode
E23xxxRealtime1 kode
E24xxxCompetitive Insights6 kode
E25xxxSendability5 kode, 1 dihentikan
E27xxxInbox Insights5 kode
E28xxxApple Messages for Business18 kode, 2 dihentikan
E32xxxKonfirmasi operasi6 kode

Terkait

Sumber daya terkait

Lanjutkan dengan dokumentasi, panduan, dan contoh untuk topik ini. Sumber daya tersedia dalam bahasa Inggris.

Dapatkan ringkasan implementasi