Idempotency

Ulangi POST dengan aman setelah timeout atau koneksi putus, tanpa membuat resource ganda.

Kirim header Idempotency-Key pada request POST. Bila jawaban tidak sampai (timeout, koneksi putus), kirim ulang request yang sama persis dengan key yang sama: resource tidak dibuat dua kali.

curl -s -X POST "$LEVIA_API/vms" \
  -H "Authorization: Bearer $LEVIA_KEY" -H "Content-Type: application/json" \
  -H "Idempotency-Key: 6f0f3c1e-8b8e-4c55-9a43-3f2a8a9c1d20" \
  -d '{"name": "web-1", "region_id": "…", "plan_id": "…", "image": "ubuntu-24-04", "ssh_key_id": "…"}'

​

Aturan

• Key: 1–255 karakter ASCII yang terlihat (tanpa spasi). UUID acak per operasi adalah pilihan yang baik. Key tidak valid → 400 idempotency_key_invalid.
• Hanya berlaku untuk POST. PUT, PATCH, dan DELETE mengabaikan header ini.
• Jawaban request pertama disimpan 24 jam, per organisasi.
• Request ulang dengan key, method, path, dan body yang sama mendapat jawaban yang sama persis (status dan body) dengan header Idempotent-Replayed: true, tanpa menjalankan aksi lagi.
• Key yang sama dengan method, path, atau body berbeda → 422 idempotency_key_reused. Buat key baru untuk operasi baru.
• Request pertama masih berjalan → 409 idempotency_in_progress. Ulangi sebentar lagi.
• Jawaban 5xx tidak disimpan, jadi request boleh diulang dengan key yang sama dan akan dijalankan lagi.
• Jawaban 4xx (mis. 422 saldo tidak cukup) disimpan dan di-replay seperti jawaban sukses. Setelah memperbaiki penyebabnya, kirim dengan key baru.

​

Password tidak pernah disimpan

Beberapa jawaban POST memuat password: reset password admin database, user database baru, dan rotasi password user. Password tidak ikut disimpan untuk replay. Pada replay, field password berisi null:

{
  "data": {
    "password": null,
    "message": "User sedang dibuat. Simpan password ini sekarang; password tidak ditampilkan lagi."
  }
}

Bila password hilang karena itu, buat password baru dengan POST /databases/{id}/reset-password (admin) atau POST /databases/{id}/users/{username}/rotate-password (user lain). Lihat Database.

​

Kapan memakainya

Pakai Idempotency-Key untuk setiap POST yang membuat resource berbayar atau menjalankan aksi: VM, volume, snapshot, floating IP, database, load balancer, backup, dan sejenisnya. Simpan key bersama catatan operasi di sistem Anda, supaya retry otomatis memakai key yang sama.