---
title: "Apakah itu kunci idempotensi? Cuba semula API dengan selamat"
description: "Kunci idempotensi ialah ID unik buatan klien yang dihantar bersama permintaan supaya cubaan semula tidak mengulang kesannya, seperti caj berganda. Cara ia berfungsi."
url: https://broadrouter.com/ms/glossary/idempotency-key/
lang: ms
updated: 2026-11-14
publisher: BroadRouter (a BroadNet site); API by BroadNet Inference, https://inference.broadnet.ai
---

Diterjemahkan daripada bahasa Inggeris dengan bantuan AI. [Baca versi asal dalam bahasa Inggeris](https://broadrouter.com/glossary/idempotency-key/) (dikemas kini 2026-11-14).

# Kunci idempotensi (idempotency key)

Dikemas kini 2026-11-14

Kunci idempotensi ialah nilai unik, biasanya ID rawak seperti UUID, yang dilampirkan oleh klien pada permintaan yang mengubah keadaan, seperti pembayaran atau pembelian. Jika permintaan yang sama dihantar semula dengan kunci yang sama, pelayan memulangkan hasil asal dan tidak melakukan tindakan itu dua kali.

Juga dikenali sebagai: idempotency key, Idempotency-Key header, idempotency token, idempotent request, idempotent retry, permintaan idempoten

Rangkaian gagal di tempat yang paling teruk: selepas pelayan bertindak tetapi sebelum anda menerima jawapan. Kunci idempotensi menjadikan cubaan semula selamat.

## Cara ia berfungsi

Klien mencipta kunci unik untuk satu tindakan yang dikehendaki dan menghantarnya bersama permintaan. Pelayan menyimpan kunci itu bersama hasilnya. Jika kunci yang sama tiba lagi, pelayan memainkan semula hasil yang disimpan dan tidak bertindak sekali lagi.

Kumpulan kerja IETF HTTPAPI sedang menyeragamkan ini sebagai pengepala permintaan `Idempotency-Key` (draf 08, Oktober 2026, belum menjadi RFC). Ia menerangkan kunci itu sebagai “a unique value generated by the client which the resource uses to recognize subsequent retries of the same request” (Terjemahan BroadRouter: “nilai unik yang dijana oleh klien yang digunakan oleh sumber untuk mengenal pasti cubaan semula seterusnya bagi permintaan yang sama”) dan mengesyorkan UUID atau ID rawak yang serupa. Kes ralat dalam draf itu:

| Situasi | Status |
| --- | --- |
| Kunci tiada apabila diperlukan | 400 Bad Request |
| Permintaan asal masih diproses | 409 Conflict |
| Kunci diguna semula dengan badan berbeza | 422 Unprocessable Content |

Builders’ Library AWS membuat perkara yang sama dari sisi klien: “APIs with side effects aren’t safe to retry unless they provide idempotency.” (Terjemahan BroadRouter: “API yang mempunyai kesan sampingan tidak selamat dicuba semula melainkan ia menyediakan idempotensi.”)

## Mengapa ia penting

Cubaan semula dengan [backoff eksponen](https://broadrouter.com/ms/glossary/exponential-backoff/) ialah amalan standard, dan banyak SDK mencuba semula secara automatik. Tanpa idempotensi, cubaan semula selepas tamat masa boleh mencipta dua pesanan atau dua caj. Dengan kunci, cubaan semula selamat walau apa pun yang dilakukan oleh cubaan pertama. Ini menjadikannya alat teras untuk ejen dan skrip yang membeli, menempah atau mencipta sesuatu tanpa manusia memerhati.

## Di BroadNet Inference

BroadNet menggunakan corak ini untuk membeli [kunci sejam](https://broadrouter.com/ms/blog/hourly-llm-api-key-explained/). `POST /portal/keys/hourly` menerima `request_id` dalam badan JSON, dan dokumentasinya menyatakan “Idempotency is required for money safety” (Terjemahan BroadRouter: “Idempotensi diperlukan untuk keselamatan wang”):

```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"}'
```

Menggunakan semula `request_id` tidak mencipta atau mengenakan caj untuk kunci lain. Selepas tamat masa, sambungan terputus, 409 `mint_in_progress` atau 5xx, cuba semula dengan `request_id` yang sama. Main semula memulangkan `already_issued: true` dan alias kunci; hanya respons berjaya yang pertama mengandungi kunci mentah. Dokumentasinya menyatakan: “Never generate a replacement id until the original result is known.” (Terjemahan BroadRouter: “Jangan sekali-kali menjana id pengganti sehingga hasil asal diketahui.”)

BroadNet tidak mendokumenkan kunci idempotensi untuk `/v1/chat/completions` atau transkripsi. Lihat [kod ralat dan cubaan semula](https://broadrouter.com/ms/guides/errors-and-retries/) untuk perkara yang patut dicuba semula di sana, dan [had kadar](https://broadrouter.com/ms/glossary/rate-limit/) untuk sebab cubaan semula membuta tuli boleh memburukkan 429.

## Soalan lazim

### Bilakah saya patut menjana kunci idempotensi baharu?

Hanya untuk tindakan baharu yang dikehendaki. Guna kunci yang sama untuk setiap cubaan semula bagi satu tindakan, dan jangan cipta kunci baharu sehingga anda tahu hasil cubaan pertama.

### Adakah permintaan chat completion LLM memerlukan kunci idempotensi?

Menjana teks tiada kesan sampingan yang kekal, jadi permintaan chat yang diulang biasanya hanya menelan kos token sekali lagi. Kunci ini penting untuk panggilan yang mengenakan caj wang atau mencipta sumber. BroadNet mendokumenkannya hanya untuk pembelian kunci sejam, bukan untuk chat completions.

### Apakah yang berlaku jika saya guna semula kunci dengan badan permintaan yang berbeza?

Draf IETF menyatakan pelayan patut menolaknya dengan 422 Unprocessable Content, kerana kunci itu sudah terikat pada permintaan lain.

## Lihat juga

-   [Backoff eksponen (exponential backoff)](https://broadrouter.com/ms/glossary/exponential-backoff/) (istilah)
-   [Had kadar (rate limit)](https://broadrouter.com/ms/glossary/rate-limit/) (istilah)
-   [Kunci API (API key)](https://broadrouter.com/ms/glossary/api-key/) (istilah)
-   [Keserentakan (concurrency)](https://broadrouter.com/ms/glossary/concurrency/) (istilah)
-   [Kod ralat BroadNet Inference dan bila perlu cuba semula](https://broadrouter.com/ms/guides/errors-and-retries/) (panduan)
-   [Kunci API kepada pelayan anda dengan senarai IP dibenarkan](https://broadrouter.com/ms/guides/api-keys-ip-allow-lists/) (panduan)
-   [Ejen yang berjalan lama: tamat masa, cubaan semula dan checkpoint](https://broadrouter.com/ms/blog/long-running-agents-timeouts-retries/) (artikel)
-   [Kunci API LLM sejam: harga rata setiap jam, diterangkan](https://broadrouter.com/ms/blog/hourly-llm-api-key-explained/) (artikel)

Cuba dengan beban kerja sebenar anda. Akaun baharu bermula dengan kredit US$5 untuk Gemma dan transkripsi. DeepSeek, GLM dan Qwen3.8 memerlukan tambah nilai.

[Mulakan](https://inference.broadnet.ai/account/?utm_source=broadrouter&utm_medium=referral&utm_campaign=ms-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 (token idempotensi)](https://builder.aws.com/content/3EumjoZascWd1oZiEgL8ORlv3qE/timeouts-retries-and-backoff-with-jitter)
-   [Rujukan API BroadNet Inference, kunci sejam (idempotensi request\_id) (Bahasa Inggeris)](https://inference.broadnet.ai/docs?utm_source=broadrouter&utm_medium=referral&utm_campaign=ms-glossary-idempotency-key&utm_content=sources#hourly-keys)
