Penanganan Kesalahan

API Publik ANKK mengembalikan kode status HTTP standar yang disertai dengan badan JSON kesalahan terperinci.

📌 Skema Kesalahan Standar

Semua respons kesalahan mematuhi skema berikut:

{
  "error": "idempotency_conflict",
  "message": "The idempotency key was already used with a different request payload.",
  "param": "idempotency_key"
}

🚦 Referensi Kode Status HTTP

Kode Status	Kode Kesalahan	Makna & Tindakan yang Direkomendasikan
`400 Bad Request`	`invalid_input`, `validation_failed`	Isi permintaan atau parameter tidak valid. Perbaiki payload.
`401 Unauthorized`	`unauthorized`, `invalid_api_key`	Kunci API hilang atau tidak valid.
`403 Forbidden`	`insufficient_scope`, `quota_exceeded`	Cakupan hilang atau kuota paket terlampaui.
`404 Not Found`	`not_found`	Sumber daya (`content_id`, `connection_id`) tidak ditemukan.
`409 Conflict`	`idempotency_conflict`	Kunci idempotensi digunakan kembali dengan payload yang tidak cocok.
`423 Locked`	`brand_locked`	Brand dikunci karena penagihan atau kebijakan. Periksa Penagihan.
`429 Too Many Requests`	`rate_limited`	Batas laju terlampaui. Tunggu sesuai `Retry-After`.
`500 Server Error`	`internal_server_error`	Masalah server internal. Dapat dicoba lagi dengan backoff.
`503 Service Unavailable`	`sns_provider_unavailable`	Layanan SNS eksternal mengalami gangguan. Coba lagi nanti.

🔍 Contoh Kesalahan Bisnis Umum

1. 403 Cakupan Tidak Cukup

{
  "error": "insufficient_scope",
  "message": "The API key does not have the required 'publishing:create' scope."
}

2. 409 Konflik Idempotensi

{
  "error": "idempotency_conflict",
  "message": "Idempotency key 'launch-001' is already bound to a different request hash.",
  "param": "idempotency_key"
}

3. 400 Validasi Media Gagal

{
  "error": "sns_content_media_maximum_exceeded",
  "message": "Bluesky supports a maximum of 4 images per post.",
  "param": "media"
}

🔁 Strategi Percobaan Ulang yang Aman

Dapat Dicoba Ulang (5xx, Batas Waktu Jaringan): Kirim ulang menggunakan idempotency_key yang sama persis dengan jitter backoff eksponensial.
Tidak Dapat Dicoba Ulang (400, 401, 403, 404, 409): Ubah kode klien atau payload, lalu terbitkan ulang di bawah kunci idempotensi baru.

🔗 Dokumentasi Terkait