Error API dan artinya
Apa arti setiap status HTTP dari API Didit dalam praktiknya - 401 dan 403 terkait kunci dan izin, masalah saldo bergaya 402, batas laju 429, dan cara membaca isi error.
Baca isi responsnya. Error Didit membawa pesan dan sering kali kode detail yang menyebutkan masalah sebenarnya - status saja jarang cukup. 401 berarti masalah kunci, 403 berarti izin atau environment, 429 berarti pembatasan laju, dan error saldo berarti masalah kredit, bukan kode.
#Baca isi responsnya terlebih dahulu
Status HTTP memberi tahu Anda kategorinya. Isi respons memberi tahu Anda apa yang sebenarnya terjadi. Hampir semua jam debugging yang sebenarnya bisa dihindari pada integrasi API dihabiskan untuk menebak-nebak kode status, padahal jawabannya ada di respons yang malah dibuang.
- Kunci yang dinonaktifkan atau berasal dari aplikasi yang salah biasanya menjadi penyebab error 401.
- Waktu terakhir digunakan memastikan apakah kunci yang menurut Anda sedang dikirim memang yang benar-benar tiba.
- Putar ulang secret jika sebuah kunci mungkin telah bocor - error 401 masih lebih baik daripada kebocoran data.
Catat isi error lengkap - status, header, dan payload - pada setiap panggilan yang gagal, di setiap environment. Anda akan membutuhkannya nanti, dan jauh lebih sulit untuk merekonstruksinya belakangan.
#Apa arti setiap status pada umumnya
| Status | Penyebab umum |
|---|---|
| 400 | Permintaan yang tidak valid - ada field wajib yang hilang, nilai enum yang salah, atau objek bersarang dengan bentuk yang keliru |
| 401 | Autentikasi gagal. Header x-api-key hilang, tidak valid, atau bukan kunci yang sah |
| 403 | Berhasil diautentikasi tetapi tidak diizinkan. Environment yang salah, izin yang tidak dimiliki kunci Anda, atau fitur yang belum diaktifkan di akun Anda |
| 404 | Resource tersebut tidak ada - atau ada di bawah aplikasi lain daripada kunci yang Anda gunakan |
| 409 | Konflik dengan status yang sudah ada, misalnya tindakan yang sudah pernah dilakukan |
| 422 | Permintaan sudah terbentuk dengan benar tetapi nilainya tidak dapat diterima - ini kegagalan validasi, bukan kegagalan sintaks |
| 429 | Dibatasi lajunya. Lihat penjelasan di bawah |
| 5xx | Masalah di sisi Didit. Coba lagi dengan backoff, dan periksa status.didit.me |
#401 vs 403 - perbedaan yang menghemat waktu Anda
401 berarti kunci tersebut sama sekali tidak diterima. Periksa apakah Anda mengirim x-api-key, apakah nilainya tidak mengandung spasi atau tanda kutip yang tidak sengaja, dan apakah Anda tidak salah menempelkan signing secret webhook alih-alih API key - keduanya adalah hal yang berbeda dan kesalahan ini sering terjadi.
403 berarti kuncinya valid tetapi panggilan ini tidak diizinkan. Ada tiga penyebab, secara berurutan:
- Environment yang tidak cocok. Field khusus sandbox (seperti
sandbox_scenario) akan ditolak pada aplikasi live, dan sebaliknya. Live dan sandbox adalah aplikasi terpisah dengan kunci yang terpisah pula. - Izin yang belum ada. Beberapa operasi membutuhkan izin yang tidak dimiliki kunci atau peran Anda. Jika Anda membutuhkan hak untuk membuat dan mengelola sesi yang belum Anda punya, itu adalah permintaan untuk tim support, bukan perbaikan kode.
- Fitur belum diaktifkan. Beberapa kapabilitas disediakan per organisasi. Jika Anda mendapat 403 pada fitur yang menurut Anda seharusnya sudah Anda miliki, sebaiknya tanyakan dulu sebelum menulis ulang panggilannya.
Tidak ada cara bawaan untuk membedakan kunci sandbox dari kunci live hanya dengan melihatnya, jadi simpan keduanya dengan nama yang jelas berbeda di secret manager Anda dan jangan pernah membiarkan satu environment variable menampung "kunci mana pun yang sedang berlaku". Kunci live yang dipakai di environment pengujian akan menghabiskan kredit sungguhan.
#404 untuk resource yang seharusnya ada
Jika sebuah sesi atau workflow mengembalikan 404 padahal Anda yakin itu ada, penyebab umumnya adalah resource tersebut ada di bawah aplikasi yang berbeda dari kunci yang Anda gunakan untuk autentikasi. Resource dibatasi lingkupnya per aplikasi; kunci dari aplikasi A tidak bisa melihat sesi milik aplikasi B.
#Error saldo dan kredit
Panggilan yang gagal karena kredit tidak cukup bukanlah masalah kode. Workflow tersebut mengandung fitur berbayar dan saldo Anda tidak mencukupinya. Ini adalah laporan "API rusak" yang paling sering terjadi, dan penyebabnya hampir selalu adalah white label, AML, atau NFC dalam workflow yang dikira gratis. Lihat mengatasi error "kredit tidak cukup".
#Pembatasan laju 429
Batas diterapkan per identifier - x-api-key Anda, atau IP klien Anda jika tidak ada kunci yang dikirim - dengan penghitung independen per scope dalam jendela geser 60 detik.
Nilai default global:
| Scope | Metode | Batas |
|---|---|---|
| Pembacaan umum | GET | 600 / menit |
| Penulisan umum | POST, PATCH, DELETE | 300 / menit |
Beberapa endpoint berdampak besar memiliki batas yang lebih ketat selain batas global tersebut, dan scope pertama yang melampaui penghitungnya adalah yang mengembalikan 429. Tabel lengkap: pembatasan laju.
Tangani 429 dengan exponential backoff dan jitter. Perulangan percobaan ulang yang rapat terhadap batas laju justru memperburuk masalah dan bisa membuat Anda terus-menerus dibatasi.
Job batch biasanya menjadi sumber error 429 - misalnya proses impor malam hari yang menembakkan beberapa ratus permintaan create dalam beberapa detik. Sebarkan pekerjaannya, bukan menaikkan concurrency sampai errornya berhenti.
#Kode detail di level fitur
Selain status HTTP, setiap pemeriksaan mengembalikan kode detailnya sendiri untuk masalah di level penyedia layanan - misalnya integrasi registry yang tidak memiliki akses ke produk tertentu di negara tertentu. Ketika Anda mendapatkan kode ini, kode tersebut menjelaskan situasinya secara tepat, jadi sertakan kode itu saat Anda menanyakannya.
Jika sebuah respons tidak menyertakan kode detail yang Anda harapkan dari katalog, sebaiknya laporkan hal ini alih-alih mencari jalan pintas - kode yang hilang adalah celah nyata, dan itu membuat masalah yang sama menjadi lebih sulit bagi orang berikutnya.
#Respons kosong bukan berarti berhasil
Pemeriksaan yang mengandalkan penyedia layanan dan mengembalikan isi kosong tidaklah sama dengan hasil yang bersih. Perlakukan "tidak ada data" sebagai kasus tersendiri di kode Anda, bukan memetakannya sebagai lolos - terutama untuk validasi database dan penyaringan wallet, di mana layanan yang belum disediakan dan hasil tidak-cocok yang sungguhan bisa terlihat serupa dari luar.
#Menguji jalur error
Sandbox memaksa kegagalan tertentu secara deterministik, yang merupakan satu-satunya cara masuk akal untuk menguji penanganan error Anda. Lihat menguji di sandbox.