Permintaan yang gagal mungkin memerlukan jeda, perbaikan field, atau kredensial yang berbeda. Respons kesalahan Bird menyediakan field yang dapat digunakan handler Anda untuk memilih tindakan tersebut.
Field error mana yang harus saya gunakan?
Gunakan type untuk penanganan umum dan code untuk pemulihan spesifik. Bird menempatkan field ini di dalam objek error tingkat atas.
Type mengelompokkan kegagalan seperti validasi, autentikasi, dan pembatasan laju permintaan. Code mengidentifikasi kegagalan tertentu, misalnya E01001 untuk validasi field.
Bird tidak pernah mengganti nama atau menggunakan ulang kode. Kode yang dihentikan tetap direservasi, sehingga pencocokan kode yang sudah ada tetap mempertahankan maknanya.
Tampilkan atau catat message, tetapi jangan cocokkan teksnya. Kata-kata bisa berubah tanpa mengubah kegagalan yang perlu ditangani handler Anda.
name membuat log mudah dibaca. doc_url menautkan ke dokumentasi kode tersebut. Catat code, name, dan request_id secara bersamaan saat operasi gagal.
Kegagalan mana yang harus dicoba ulang?
Coba ulang kegagalan sementara dengan kebijakan yang dibatasi. Perbaiki masalah input dan kredensial sebelum mencoba lagi. Periksa kode spesifik jika satu status bisa memerlukan tindakan yang berbeda.
| Respons | Tindakan default |
|---|---|
429, E01003 | Tunggu Retry-After, lalu coba lagi. |
500, 502, 503 atau 504 | Coba lagi dengan jeda bertahap dan batas percobaan. |
501 | Hentikan dan periksa operasi mana yang didukung server. |
401 atau 403 | Perbaiki kredensial atau izinnya sebelum mencoba lagi. |
| Validasi field atau input tidak valid | Perbaiki field yang diidentifikasi oleh respons. |
409, E01004 | Tunggu operasi yang sedang berjalan sebelum mencoba lagi. |
409, E01005 | Perbaiki penggunaan ulang idempotency key dengan input yang berbeda. |
Gunakan idempotency key yang sama saat mencoba ulang operasi tulis yang sama. Timeout atau kegagalan server tidak membuktikan bahwa operasi awal tidak melakukan apa pun.
Hentikan saat anggaran percobaan ulang habis dan catat error terakhir. Mengulangi permintaan yang sama tanpa batas bisa menyembunyikan kegagalan yang memerlukan intervensi.
Bagaimana cara menangani error validasi field?
Baca array details pada E01001 ValidationError dan kaitkan setiap entri dengan param-nya. Tampilkan message entri tersebut di samping field yang bermasalah.
Jangan parsing pesan-pesan tersebut untuk mengidentifikasi field atau kegagalan. Kata-katanya bisa berubah, sama seperti pesan tingkat atas.
Permintaan yang salah format bisa mengembalikan E01002 InvalidRequest. Gunakan pemulihan yang didokumentasikan daripada mengasumsikan setiap kegagalan input berisi detail tingkat field.
Bisakah respons memberi tahu cara pemulihan?
Beberapa error menyertakan remediation, langkah berikutnya yang dapat dibaca manusia, atau next, daftar operasi berurutan untuk dicoba.
Tampilkan remediasi jika membantu pengguna memperbaiki masalah. Misalnya, kegagalan otorisasi mungkin memerlukan kredensial dengan scope tambahan.
Handler otomatis dapat menggunakan next untuk memilih operasi pemulihan. Handler tersebut tetap memerlukan input dan izin operasi itu sebelum menjalankannya.
vendor_code mengidentifikasi kegagalan di hilir, seperti respons SMTP atau penolakan pembayaran. Periksa kode penyedia tersebut jika pemulihan bergantung padanya.
Apa yang harus terjadi untuk kode yang tidak dikenal?
Sediakan branch default yang mencatat kegagalan tanpa crash atau percobaan ulang tanpa batas. Kode dan type baru bisa muncul seiring berkembangnya API.
Terapkan kebijakan coba ulang berbasis status yang sudah diketahui jika sesuai. Jika tidak, hentikan dan catat kode beserta request ID-nya untuk investigasi.
Panduan error mendokumentasikan struktur respons kesalahan. Referensi error mencantumkan kode-kode individual beserta panduan pemulihannya.
Singkatnya
Cocokkan kode, bukan pesan.
Bird tidak pernah mengganti nama atau menggunakan ulang kode error, tetapi pesan yang dapat dibaca manusia bisa berubah.
Coba ulang kegagalan sementara dengan batas.
Tunggu saat terkena pembatasan laju permintaan dan tambahkan jeda bertahap pada kegagalan server sementara. Gunakan idempotency key yang sama untuk operasi tulis yang diulang.
Baca detail validasi.
E01001menyertakan masalah field dalamdetails. Gunakan setiapparamuntuk mengaitkan pesannya dengan input yang bermasalah.Sediakan fallback untuk error yang tidak dikenal.
Catat kode yang tidak dikenali beserta request ID-nya agar kegagalan baru tidak merusak handler Anda.