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, percobaan ulang, 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) jika dikembalikan.

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 kesalahan native bahasanya dan membawa setiap field envelope (type, code, message, doc_url, request_id, ...) pada nilai kesalahan.

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 kesalahan

Semua kode kesalahan 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 & identitas24 kode, 2 dihentikan
E03xxxBilling & paket langganan15 kode, 2 dihentikan
E04xxxPengiriman & penyampaian email87 kode, 3 dihentikan
E05xxxDomain & DNS19 kode
E06xxxWebhook11 kode
E07xxxWallet4 kode
E08xxxPengelolaan workspace dan organisasi1 kode, 2 dihentikan
E10xxxKuota16 kode, 2 dihentikan
E11xxxIP pool & IP khusus4 kode, 1 dihentikan
E12xxxPengiriman & penyampaian SMS62 kode, 5 dihentikan
E13xxxVerify7 kode, 1 dihentikan
E14xxxNomor6 kode
E15xxxPengiriman & penyampaian WhatsApp75 kode
E16xxxTrust1 kode
E17xxxKotak masuk agen16 kode, 2 dihentikan
E19xxxKepatuhan registrasi6 kode
E20xxxAset & pustaka media15 kode
E21xxxSuara & trunking SIP20 kode, 9 dihentikan
E22xxxPencarian nomor5 kode
E23xxxRealtime1 kode
E24xxxCompetitive Insights6 kode
E25xxxSendability5 kode, 1 dihentikan
E26xxxeSIM19 kode
E27xxxInbox Insights9 kode
E28xxxApple Messages for Business48 kode, 2 dihentikan
E32xxxKonfirmasi operasi6 kode
E33xxxKelayakan organisasi3 kode, 1 dihentikan
E34xxxKonektor1 kode, 1 dihentikan

Terkait