Error

Setiap request Bird API yang gagal mengembalikan envelope JSON yang sama, bersarang di bawah key tingkat atas error. Berikut adalah respons nyata untuk request pengiriman dengan body kosong:

Contoh kode

{
  "error": {
    "type": "validation_error",
    "code": "E01001",
    "name": "ValidationError",
    "message": "Request has 1 validation error.",
    "doc_url": "https://bird.com/docs/api/errors/E01001",
    "request_id": "req_01ky7q3hckecgv6d7jpq865532",
    "details": [{ "param": "body", "message": "missing properties 'from', 'to'" }]
  }
}

Status HTTP mengikuti type. Error klien menggunakan 400 untuk request yang salah format, 401 atau 403 untuk kegagalan akses, 402 untuk billing, dan 404 untuk resource yang tidak ditemukan. Error klien menggunakan 409 untuk konflik, 412 untuk prasyarat yang tidak terpenuhi, 422 untuk kegagalan validasi dan aturan bisnis, serta 429 untuk pembatasan laju permintaan. Kegagalan sisi Bird menggunakan 5xx. Status mengidentifikasi kategori; envelope menjelaskan apa yang terjadi.

Field envelope

Field	Peran
type	Kategori umum untuk branching kasar: validation_error, auth_error, permission_error, not_found_error, conflict_error, rate_limit_error, billing_error, internal_error, dan beberapa lainnya. Enum tertutup yang jarang bertambah.
code	Identifier opak dan stabil (E01001). Referensi kanonik: unik, tidak pernah diganti nama, tidak pernah dipakai ulang. Saat sebuah error dihentikan, kodenya dicadangkan secara permanen.
name	Slug yang dapat dibaca manusia (ValidationError) untuk keterbacaan log. Selalu dipasangkan dengan code, bukan penggantinya.
message	Deskripsi yang dapat dibaca manusia. Tidak stabil: kata-kata dapat berubah tanpa pemberitahuan. Tampilkan, catat ke log, jangan pernah di-parse.
param	Untuk error terkait input, field yang bermasalah. Dihilangkan jika tidak berlaku.
doc_url	Link stabil ke halaman dokumentasi untuk kode ini.
request_id	Selalu ada, dan juga dikembalikan sebagai header respons X-Request-Id. Sertakan dalam permintaan dukungan; ini memungkinkan Bird melacak request yang tepat.
details	Masalah validasi per field. Hanya ada pada respons validation_error.
remediation	Langkah selanjutnya yang dapat dibaca manusia untuk mengatasi error. Ada jika pemulihan diketahui.
next	Operasi yang mengatasi error, dalam urutan yang harus dicoba. Ada untuk error dengan pemulihan yang terdefinisi jelas, seperti prasyarat yang tidak terpenuhi.
vendor_code	Kode asli dari sistem hilir (kode respons SMTP, kode penolakan pembayaran). Hanya ada saat Bird meneruskan kode dari sistem eksternal yang mungkin perlu Anda tindak lanjuti.

Lakukan branching berdasarkan type untuk penanganan umum dan code untuk penanganan spesifik, jangan pernah berdasarkan message. Klien biasa melakukan switch pada type (coba lagi pada rate_limit_error, tampilkan validation_error ke pengguna, hubungi seseorang pada internal_error) dan mencocokkan nilai code individual hanya untuk beberapa error yang ditangani secara khusus.

Kode seperti E04012 sengaja dibuat opak. Setiap kode menautkan ke halaman dokumentasi melalui doc_url, yang menjelaskan penyebab dan cara mengatasinya. Katalog lengkap ada di referensi error.

Kegagalan validasi: satu kode, banyak detail

Validasi tingkat field tidak mendapatkan kode terpisah untuk setiap kombinasi field dan kegagalan. Setiap kegagalan validasi adalah E01001 ValidationError dengan array details yang mencantumkan setiap masalah tingkat field sebagai {param, message}, seperti cara kegagalan pengiriman yang tertangkap mencantumkan properti yang hilang. String message di dalam details dapat berubah dan hanya boleh ditampilkan. Gunakan param untuk memetakan masalah ke field formulir.

Panduan pemulihan: remediasi dan langkah selanjutnya

Error dengan perbaikan yang diketahui menyertakannya dalam envelope. Berikut adalah respons nyata untuk panggilan webhooks yang dibuat dengan key API yang tidak memiliki scope yang diperlukan:

Contoh kode

{
  "error": {
    "type": "permission_error",
    "code": "E02035",
    "name": "InsufficientScope",
    "message": "This request requires the \"webhooks:read\" scope, which your credential has not been granted.",
    "param": "webhooks:read",
    "doc_url": "https://bird.com/docs/api/errors/E02035",
    "request_id": "req_01ky7q4665emc9tw1pxkptaqwq",
    "remediation": "Re-authenticate with a credential that has been granted the required scope, then retry."
  }
}

remediation adalah kalimat untuk manusia atau log agen; next, jika ada, mencantumkan operasi API yang mengatasi error dalam urutan yang harus dicoba (verifikasi domain, lalu coba lagi pengiriman). Agen dan CLI dapat menjalankan next secara langsung; klien interaktif dapat menampilkan remediation apa adanya.

Menangani error dengan baik

Coba lagi 429 dan 5xx, tidak ada yang lain secara default. Patuhi Retry-After pada pembatasan laju permintaan (lihat Pembatasan laju permintaan), gunakan exponential backoff pada 5xx, dan kirim Idempotency-Key agar retry pada request yang mengubah data aman.
Catat code, name, dan request_id bersama-sama. Kode adalah yang akan Anda cari di dokumentasi dan log Anda sendiri; request ID adalah yang dibutuhkan dukungan.
Toleransi kode dan tipe baru. Kode error baru dikirimkan secara berkala seiring produk berkembang, dan enum type sesekali bertambah nilainya. Tulis handler Anda dengan branch default yang wajar, bukan pencocokan yang lengkap.

Langkah selanjutnya

Referensi error: katalog error lengkap, satu halaman per kode
Idempotensi: retry yang aman untuk request yang mengubah data
Pembatasan laju permintaan: header limit dan panduan backoff

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 integration Panduan implementasiSend your first email

Dapatkan ringkasan implementasi