Panduan

Penanganan error

Aplikasi harus membaca status HTTP dan struktur respons error. Jangan menjadikan teks pesan error sebagai aturan bisnis.

Status	Arti	Tindakan aplikasi
`2xx`	Permintaan diterima.	Periksa struktur respons sebelum data digunakan.
`400`	Format body atau parameter tidak valid.	Perbaiki request berdasarkan detail validasi; jangan mencoba ulang request yang sama.
`401`	Kredensial tidak ada, tidak valid, dicabut, atau kedaluwarsa.	Periksa API key dan pastikan key masih aktif.
`403`	Kredensial valid tetapi izin tidak mencukupi.	Gunakan key dengan paket dan izin yang sesuai atau hubungi administrator.
`429`	Permintaan melewati batas yang berlaku.	Tunggu sesuai `Retry-After` atau `X-RateLimit-RetryAfter`, lalu gunakan exponential backoff.
`503`	Layanan atau validasi rate limit sementara tidak tersedia.	Coba kembali secara terbatas dengan backoff dan jitter.

Format respons error

Jika respons error memiliki body JSON, API menggunakan Problem Details. Field type, title, dan status menjelaskan kegagalan; field tambahan dapat muncul sesuai jenis error. Respons autentikasi tertentu dapat hanya mengembalikan status HTTP tanpa body.

{
  "type": "https://tools.ietf.org/html/rfc6585#section-4",
  "title": "API rate limit exceeded.",
  "status": 429
}

Error validasi dapat menambahkan object errors yang berisi nama field dan daftar masalahnya:

{
  "title": "One or more validation errors occurred.",
  "status": 400,
  "errors": {
    "DateFrom": ["The supplied value is invalid."]
  }
}

Gunakan status HTTP dan nama field untuk pengambilan keputusan. Teks title, detail, dan isi pesan validasi dapat berubah dan tidak boleh dijadikan konstanta aturan bisnis.

Mencoba kembali dengan aman

Tetapkan timeout dan jumlah percobaan ulang maksimum.
Tambahkan jitter pada exponential backoff agar permintaan tidak menumpuk bersamaan.
Jangan mengulang permintaan yang mengubah data tanpa memahami aturan idempotency.
Jangan merekam kredensial atau seluruh isi respons ke dalam log.

Header rate limit

Request menggunakan API key dapat mengembalikan X-RateLimit-Limit, X-RateLimit-Remaining, dan X-RateLimit-Reset. Nilai reset menunjukkan jumlah detik sampai jendela rate limit berikutnya.