Kode Kesalahan

Saat gagal, periksa kode status HTTP dan field message.

Isi Respons Error

Error bisnis selalu mengembalikan code yang dapat dibaca mesin agar bisa ditangani secara terprogram. Parameter tidak valid (validasi) dan rute tidak dikenal mengembalikan format standar Laravel: { “message”: ”…”, “errors”: { … } }. Validasi input sebelum mengirim.

{
  "code": "insufficient_balance",
  "message": "Insufficient balance. Please top up and try again."
}

Kesalahan

code	HTTP	Deskripsi
unauthorized	401	Kunci API hilang, tidak valid, atau tidak aktif.
account_banned	403	Akun ditangguhkan. Hubungi dukungan.
invalid_realtime_request	400	Permintaan realtime tidak valid (mis. nomor telepon tanpa prefiks internasional + saat country dikosongkan).
idempotency_key_required	400	Permintaan realtime wajib menyertakan header Idempotency-Key.
invalid_idempotency_key	422	Idempotency-Key tidak valid: 1-128 karakter huruf, angka, dan . _ : -
idempotency_conflict	409	Idempotency-Key yang sama digunakan untuk isi permintaan yang berbeda.
request_in_progress	409	Permintaan realtime identik masih diproses. Coba lagi sebentar lagi (Retry-After: 1).
empty_input	422	Berkas yang diunggah tidak berisi baris yang dapat dipakai.
product_not_found	422	Slug produk yang dikirim tidak ada atau tidak aktif.
product_mode_not_supported	422	Endpoint ini tidak menerima mode produk ini (produk realtime tidak untuk endpoint massal).
invalid_country	422	Produk ini tidak mendukung negara yang dikirim.
too_few_numbers	422	Jumlah pengiriman di bawah minimum produk.
too_many_numbers	422	Jumlah pengiriman melebihi maksimum platform.
insufficient_balance	402	Saldo tidak cukup. Isi ulang lalu coba lagi.
realtime_disabled	403	Deteksi realtime belum diaktifkan untuk akun ini.
realtime_rate_limited	429	Batas laju realtime terlampaui. Hormati retry_after.
product_pricing_unavailable	503	Harga produk ini belum dikonfigurasi. Hubungi dukungan.
detection_capacity_unavailable	503	Tidak ada kapasitas deteksi saat ini. Coba lagi nanti.
realtime_route_unavailable	503	Tidak ada rute realtime yang tersedia. Coba lagi nanti.
realtime_fact_cache_unavailable	503	Dependensi realtime sementara tidak tersedia. Coba lagi nanti.
realtime_rate_limiter_unavailable	503	Rate limiter sementara tidak tersedia. Coba lagi nanti.
internal_error	500	Kesalahan server tak terduga. Aman untuk mencoba ulang dengan Idempotency-Key yang sama.

Kegagalan tanpa kode

Tidak semua kegagalan punya code. Endpoint tugas melaporkan empat kondisi hanya lewat status HTTP dan message, karena kegagalan itu muncul sebelum jalur error bisnis tercapai:

HTTP	Kondisi	Body
404	task_id tidak ada, atau milik akun lain	hanya message
404	GET /v1/tasks/{token}/download — file hasil tidak tersedia, kedaluwarsa, atau tidak lagi dapat diunduh	hanya message
422	GET /v1/tasks/{token}/result — hasil belum siap: tugas belum selesai, file belum dibuat, atau sudah kedaluwarsa	hanya message
422	Parameter permintaan gagal validasi	{ "message": …, "errors": { … } }

Untuk kasus ini, bercabanglah berdasarkan status HTTP. message ditujukan untuk log dan untuk orang yang membaca insiden, bukan untuk alur kontrol.

Kirim Accept: application/json

Body ini berformat JSON bila permintaan meminta JSON. Klien yang tidak mengirim header Accept bisa menerima halaman error HTML — pengalaman yang menyulitkan saat menelusuri masalah dini hari. Semua contoh di dokumentasi ini mengirim JSON.

Mencoba Ulang

Respons yang tepat terhadap kegagalan bergantung pada apakah mengulang permintaan dapat menghasilkan jawaban yang berbeda.

Perlu tindakan lebih dulu

Percobaan ulang tanpa perubahan akan mengulangi kegagalan yang sama.

unauthorized, account_banned, invalid_realtime_request, idempotency_key_required, invalid_idempotency_key, idempotency_conflict, empty_input, product_not_found, product_mode_not_supported, invalid_country, too_few_numbers, too_many_numbers, insufficient_balance, realtime_disabled, product_pricing_unavailable

Tunggu, lalu coba ulang

Bersifat sementara — permintaan yang sama semestinya berhasil nanti.

realtime_rate_limited, request_in_progress, detection_capacity_unavailable, realtime_route_unavailable, realtime_fact_cache_unavailable, realtime_rate_limiter_unavailable

Hasil tidak pasti

Permintaan mungkin sudah diterapkan atau belum. Coba ulang dengan kunci yang sama.

internal_error