---
title: "Apa itu idempotency key? Retry API yang aman | BroadRouter"
description: "Idempotency key adalah ID unik buatan klien yang dikirim bersama request agar retry tidak mengulang efeknya, seperti tagihan ganda. Cara kerja dan header IETF-nya."
url: https://broadrouter.com/id/glossary/idempotency-key/
lang: id
updated: 2026-11-14
publisher: BroadRouter (a BroadNet site); API by BroadNet Inference, https://inference.broadnet.ai
---

Diterjemahkan dari bahasa Inggris dengan bantuan AI. [Baca versi asli bahasa Inggris](https://broadrouter.com/glossary/idempotency-key/) (diperbarui 2026-11-14).

# Idempotency key

Diperbarui 2026-11-14

Idempotency key adalah nilai unik, biasanya ID acak seperti UUID, yang dilampirkan klien pada request yang mengubah state, misalnya pembayaran atau pembelian. Jika request yang sama dikirim lagi dengan key yang sama, server mengembalikan hasil aslinya alih-alih menjalankan aksi itu dua kali.

Disebut juga: kunci idempotensi, idempotency key, request idempoten, retry aman, Idempotency-Key header, idempotency token, idempotent request, idempotent retry

Jaringan gagal di tempat terburuk: setelah server bertindak, tetapi sebelum Anda menerima jawabannya. Idempotency key membuat retry menjadi aman.

## Cara kerjanya

Klien membuat key unik untuk satu aksi yang dimaksud dan mengirimkannya bersama request. Server menyimpan key itu bersama hasilnya. Jika key yang sama datang lagi, server mengirim ulang hasil yang tersimpan alih-alih bertindak lagi.

Working group IETF HTTPAPI sedang menstandarkan ini sebagai request header `Idempotency-Key` (draf 08, Oktober 2026, belum menjadi RFC). Draf itu menggambarkan key sebagai “a unique value generated by the client which the resource uses to recognize subsequent retries of the same request” (terjemahan: nilai unik yang dibuat klien, yang dipakai resource untuk mengenali retry berikutnya dari request yang sama) dan merekomendasikan UUID atau ID acak serupa. Kasus error dalam draf:

| Situasi | Status |
| --- | --- |
| Key tidak ada padahal wajib | 400 Bad Request |
| Request asli masih diproses | 409 Conflict |
| Key dipakai ulang dengan body berbeda | 422 Unprocessable Content |

Builders’ Library dari AWS menyampaikan hal yang sama dari sisi klien: “APIs with side effects aren’t safe to retry unless they provide idempotency.” (terjemahan: API yang punya efek samping tidak aman untuk di-retry kecuali menyediakan idempotensi.)

## Kenapa ini penting

Retry dengan [exponential backoff](https://broadrouter.com/id/glossary/exponential-backoff/) adalah praktik standar, dan banyak SDK melakukan retry otomatis. Tanpa idempotensi, retry setelah timeout bisa membuat dua pesanan atau dua tagihan. Dengan key, retry aman apa pun yang dilakukan percobaan pertama. Itulah yang menjadikannya alat inti bagi agen dan skrip yang membeli, memesan, atau membuat sesuatu tanpa diawasi manusia.

## Di BroadNet Inference

BroadNet memakai pola ini untuk pembelian [kunci per jam](https://broadrouter.com/id/blog/hourly-llm-api-key-explained/). `POST /portal/keys/hourly` menerima `request_id` di body JSON, dan dokumentasinya menyatakan “Idempotency is required for money safety” (terjemahan: idempotensi wajib demi keamanan uang):

```bash
curl -X POST https://inference.broadnet.ai/portal/keys/hourly \
  -H "Authorization: Bearer <portal-credential>" \
  -H "Content-Type: application/json" \
  -d '{"request_id":"order-20260920-001","label":"kiosk-1"}'
```

Memakai ulang `request_id` tidak membuat atau menagih key lain. Setelah timeout, koneksi terputus, 409 `mint_in_progress`, atau 5xx, lakukan retry dengan `request_id` yang sama. Replay mengembalikan `already_issued: true` dan alias key-nya; hanya respons sukses pertama yang berisi key mentah. Dokumentasinya menyebut: “Never generate a replacement id until the original result is known.” (terjemahan: Jangan pernah membuat id pengganti sebelum hasil aslinya diketahui.)

BroadNet tidak mendokumentasikan idempotency key untuk `/v1/chat/completions` atau transkripsi. Lihat [kode error dan retry](https://broadrouter.com/id/guides/errors-and-retries/) untuk apa yang perlu di-retry di sana, dan [rate limit](https://broadrouter.com/id/glossary/rate-limit/) untuk alasan retry membabi buta bisa memperparah 429.

## Pertanyaan umum

### Kapan saya harus membuat idempotency key baru?

Hanya untuk aksi baru yang memang dimaksudkan. Gunakan key yang sama untuk setiap retry dari satu aksi, dan jangan buat key baru sampai Anda tahu hasil percobaan pertama.

### Apakah request chat completion LLM perlu idempotency key?

Menghasilkan teks tidak punya efek samping permanen, jadi request chat yang terulang biasanya hanya memakan biaya token lagi. Key ini penting untuk panggilan yang menagih uang atau membuat resource. BroadNet hanya mendokumentasikannya untuk pembelian kunci per jam, bukan untuk chat completions.

### Apa yang terjadi jika saya memakai ulang key dengan body request yang berbeda?

Menurut draf IETF, server sebaiknya menolaknya dengan 422 Unprocessable Content, karena key itu sudah terikat ke request lain.

## Lihat juga

-   [Exponential backoff](https://broadrouter.com/id/glossary/exponential-backoff/) (istilah)
-   [Rate limit (batas laju)](https://broadrouter.com/id/glossary/rate-limit/) (istilah)
-   [Kunci API (API key)](https://broadrouter.com/id/glossary/api-key/) (istilah)
-   [Konkurensi (concurrency)](https://broadrouter.com/id/glossary/concurrency/) (istilah)
-   [Kode error BroadNet Inference dan kapan harus mencoba ulang](https://broadrouter.com/id/guides/errors-and-retries/) (panduan)
-   [Batasi kunci API ke server Anda dengan IP allow-list](https://broadrouter.com/id/guides/api-keys-ip-allow-lists/) (panduan)
-   [Agent yang berjalan lama: timeout, retry, dan checkpoint yang andal](https://broadrouter.com/id/blog/long-running-agents-timeouts-retries/) (artikel)
-   [Kunci API LLM per jam: harga tetap per jam, dijelaskan](https://broadrouter.com/id/blog/hourly-llm-api-key-explained/) (artikel)

Coba dengan beban kerja Anda yang sebenarnya. Akun baru mendapat kredit US$5 untuk Gemma dan transkripsi. DeepSeek, GLM, dan Qwen3.8 memerlukan top up.

[Mulai](https://inference.broadnet.ai/account/?utm_source=broadrouter&utm_medium=referral&utm_campaign=id-glossary-idempotency-key&utm_content=page-cta) ·

**Sumber**

-   [IETF HTTPAPI, The Idempotency-Key HTTP Header Field (Internet-Draft)](https://datatracker.ietf.org/doc/draft-ietf-httpapi-idempotency-key-header/)
-   [AWS Builders' Library, Timeouts, retries and backoff with jitter (idempotency token)](https://builder.aws.com/content/3EumjoZascWd1oZiEgL8ORlv3qE/timeouts-retries-and-backoff-with-jitter)
-   [Referensi API BroadNet Inference, kunci per jam (idempotensi request\_id) (bahasa Inggris)](https://inference.broadnet.ai/docs?utm_source=broadrouter&utm_medium=referral&utm_campaign=id-glossary-idempotency-key&utm_content=sources#hourly-keys)
