Errors

Semua kesalahan API Volara memakai amplop error JSON yang konsisten, sehingga client bisa menanganinya secara seragam.

Amplop error

{
  "error": {
    "code": "validation_error",
    "message": "Field 'to' wajib diisi.",
    "details": [
      { "field": "to", "issue": "required" }
    ]
  }
}

• code — kode mesin yang stabil (snake_case) untuk percabangan logika.
• message — pesan yang dapat dibaca manusia (Bahasa Indonesia/Inggris).
• details — opsional; konteks tambahan (mis. error validasi per-field).

Kode status HTTP

Status	Arti	Tindakan
400	Bad Request — payload/parameter tidak valid	Perbaiki request; baca details.
401	Unauthorized — API key salah/tidak ada/dicabut	Periksa Autentikasi.
403	Forbidden — kunci tidak punya scope/akses	Cek scope kunci atau grant agency.
404	Not Found — resource tidak ada di tenant ini	Verifikasi id milik tenant Anda.
409	Conflict — bentrok state/idempotency	Cek state resource atau ulangi dengan idempotency-key baru.
422	Unprocessable — validasi gagal	Baca details.
429	Too Many Requests — rate limit	Backoff; lihat Rate Limits.
5xx	Server error	Retry dengan backoff; jika berlanjut, hubungi dukungan.

Pola penanganan

Percabangkan logika pada error.code (stabil), bukan pada error.message (bisa berubah). Tampilkan message ke pengguna seperlunya.

Kode referensi klien VLR-*

Sebagian respons error menyertakan kode referensi VLR-* (mis. VLR-7F3A2C). Kode ini ditampilkan ke pengguna akhir saat terjadi kegagalan dan dipakai sebagai tautan ke detail kejadian di admin. Saat melapor ke dukungan, sertakan kode VLR-* agar tim dapat melacak kejadian persisnya tanpa membuka data sensitif.

Contoh penanganan

const res = await fetch('https://api.volara.chat/api/v1/messages', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.VOLARA_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ channelId, to, type: 'text', text: 'Halo!' }),
})

if (!res.ok) {
  const { error } = await res.json()
  switch (error?.code) {
    case 'rate_limited':
      // tunggu lalu retry — lihat header RateLimit-Reset
      break
    case 'validation_error':
      console.error('Validasi:', error.details)
      break
    default:
      console.error(`[${res.status}] ${error?.message}`)
  }
}

Langkah selanjutnya

• Rate Limits untuk penanganan 429.
• Referensi API interaktif untuk kode error per-endpoint.