Lewati ke konten utama
Kontak Sales

Panduan Lengkap Kamus Error API Biteship dan Solusinya

Biteship
Diperbarui

Saat mengintegrasikan API Biteship ke dalam sistem Anda, beberapa kendala atau pesan galat (error) mungkin terjadi. Artikel ini berfungsi sebagai Kamus Error API untuk membantu Anda memahami kode status, penyebab umum kegagalan permintaan, dan langkah penyelesaiannya secara mandiri.

Artikel ini akan membantu Anda memahami:

  • Struktur umum respon error API Biteship
  • Daftar kode status HTTP dan maknanya
  • Kategori pesan galat yang sering ditemui
  • Panduan langkah penanganan (troubleshooting)
  • Cara menghubungi tim dukungan teknis

1. Struktur Respon Error API

Setiap kali permintaan API mengalami kegagalan, API Biteship akan mengembalikan respon berformat JSON yang berisi detail kegagalan.

Secara umum, atribut yang dikembalikan meliputi:

  • code: Kode status numerik HTTP.
  • success: Bernilai false jika terjadi kendala.
  • error: Pesan singkat mengenai jenis kendala.
  • message: Penjelasan rinci mengenai penyebab error.

2. Daftar Kode Status HTTP Utama

Berikut adalah daftar kode status yang paling sering dikembalikan oleh server saat terjadi kendala:

  • 400 Bad Request: Format permintaan tidak sesuai atau parameter wajib tidak diisi.
  • 401 Unauthorized: API Key / Token autentikasi tidak valid atau hilang.
  • 403 Forbidden: Akun Anda tidak memiliki akses ke fitur atau endpoint tertentu.
  • 404 Not Found: Resource (seperti ID pengiriman atau kurir) tidak ditemukan.
  • 422 Unprocessable Entity: Validasi data gagal (contoh: format nomor telepon salah).
  • 429 Too Many Requests: Pengiriman request melebihi batas (rate limit).
  • 500 Internal Server Error: Terjadi kendala internal pada server Biteship.

3. Rincian Error dan Solusinya

Error Autentikasi & Akses (401 / 403)

Penyebab umum:

  • Gagal memasukkan header Authorization.
  • Menggunakan API Key Sandbox pada environment Production (atau sebaliknya).
  • Akun bisnis belum diverifikasi untuk akses fitur tertentu.

Solusi:

  • Pastikan header Authorization diisi dengan format Bearer YOUR_API_KEY.
  • Periksa kembali dashboard untuk memastikan API Key yang digunakan sesuai dengan environment.

Error Validasi Parameter (400 / 422)

Penyebab umum:

  • Pengisian koordinat latitude/longitude di luar batas area valid.
  • Berat barang bernilai 0 atau kurang.
  • Kode pos tidak ditemukan atau tidak sesuai dengan kecamatan.
  • Format nomor HP penerima tidak sesuai.

Solusi:

  • Pastikan seluruh payload JSON telah sesuai dengan dokumentasi resmi API Biteship.
  • Lakukan validasi input di sisi aplikasi Anda sebelum mengirim permintaan ke API.

Error Terkait Kurir & Pengiriman

Penyebab umum:

  • Layanan kurir yang dipilih tidak mendukung rute asal-tujuan tersebut.
  • Ukuran atau berat paket melebihi batas maksimal kurir.
  • Jam operasional penjemputan (pickup) kurir sudah terlewati.

Solusi:

  • Gunakan endpoint cek tarif terlebih dahulu untuk memvalidasi ketersediaan kurir.
  • Sesuaikan dimensi dan berat paket dengan ketentuan kurir mitra.

4. Langkah-Langkah Penanganan Mandiri (Troubleshooting)

Langkah 1: Periksa Pesan Response Body

Baca atribut message pada respon JSON untuk melihat bidang (field) mana yang menyebabkan kegagalan.

Langkah 2: Cek API Key dan Environment

Pastikan Anda menggunakan credential yang tepat untuk Sandbox maupun Production.

Langkah 3: Gunakan API Log di Dashboard

Masuk ke dashboard Biteship pada bagian API Logs untuk melihat riwayat request dan response secara akurat.

Langkah 4: Uji Coba melalui Postman

Lakukan isolasi kendala dengan mencoba payload yang sama pada API Client seperti Postman.

5. FAQ Kendala API

Mengapa saya mendapat respon 429 Too Many Requests?

Anda telah melebihi ambang batas pemanggilan API per menit. Silakan beri jeda (rate limiting/backoff strategy) pada aplikasi Anda sebelum mengirim permintaan kembali.

Mengapa kurir tertentu tidak muncul saat cek tarif?

Hal ini bisa terjadi jika lokasi asal/tujuan belum terjangkau oleh kurir tersebut, atau berat paket melebihi batas maksimum layanan.

Apa yang harus dilakukan jika menerima error status 500?

Error 500 mengindikasikan masalah pada server atau gangguan sementara pada sistem mitra kurir. Tunggu beberapa saat lalu coba kembali, atau hubungi tim support jika kendala berlanjut.

6. Kesimpulan

Sebagian besar kendala integrasi API dapat diatasi dengan memastikan format data, autentikasi, serta parameter input telah sesuai dengan panduan dokumentasi.

Jika Anda masih menemui kendala yang belum teratasi melalui panduan ini, silakan hubungi tim teknis Biteship dengan melampirkan Request Body, Response Body, dan X-Request-ID melalui email ke support@biteship.com.

Terkait dengan