---
title: "Idempotency key là gì? Thử lại API một cách an toàn | BroadRouter"
description: "Idempotency key là ID duy nhất do client tạo và gửi kèm request để lần thử lại không lặp lại tác động, như trừ tiền hai lần. Cách hoạt động và header của IETF."
url: https://broadrouter.com/vi/glossary/idempotency-key/
lang: vi
updated: 2026-11-14
publisher: BroadRouter (a BroadNet site); API by BroadNet Inference, https://inference.broadnet.ai
---

Được dịch từ tiếng Anh với sự hỗ trợ của AI. [Đọc bản gốc tiếng Anh](https://broadrouter.com/glossary/idempotency-key/) (cập nhật ngày 2026-11-14).

# Idempotency key (khóa idempotency)

Cập nhật 2026-11-14

Idempotency key là một giá trị duy nhất, thường là ID ngẫu nhiên như UUID, mà client gắn vào request làm thay đổi trạng thái, chẳng hạn thanh toán hay mua hàng. Nếu cùng request được gửi lại với cùng key, server trả về kết quả ban đầu thay vì thực hiện hai lần.

Còn gọi là: idempotency key là gì, khóa idempotency, idempotent là gì, request idempotent, chống trừ tiền hai lần, Idempotency-Key header, idempotency key, idempotency token, idempotent request, idempotent retry

Mạng luôn hỏng ở chỗ tệ nhất: sau khi server đã thực hiện nhưng trước khi bạn nhận được phản hồi. Idempotency key giúp lần thử lại trở nên an toàn.

## Cách hoạt động

Client tạo một key duy nhất cho một hành động dự định và gửi nó kèm request. Server lưu key cùng với kết quả. Nếu cùng key đó tới lần nữa, server trả lại kết quả đã lưu thay vì thực hiện lại.

Nhóm làm việc IETF HTTPAPI đang chuẩn hóa cơ chế này thành header request `Idempotency-Key` (bản thảo 08, tháng 10 năm 2026, chưa phải RFC). Bản thảo mô tả key là “a unique value generated by the client which the resource uses to recognize subsequent retries of the same request” (Bản dịch: một giá trị duy nhất do client tạo, được tài nguyên dùng để nhận ra các lần thử lại sau đó của cùng một request) và khuyến nghị UUID hoặc một ID ngẫu nhiên tương tự. Các trường hợp lỗi trong bản thảo:

| Tình huống | Mã trạng thái |
| --- | --- |
| Thiếu key ở nơi bắt buộc | 400 Bad Request |
| Request ban đầu vẫn đang xử lý | 409 Conflict |
| Key được dùng lại với body khác | 422 Unprocessable Content |

AWS Builders’ Library nêu cùng ý từ phía client: “APIs with side effects aren’t safe to retry unless they provide idempotency.” (Bản dịch: API có tác dụng phụ không an toàn để thử lại trừ khi chúng hỗ trợ idempotency.)

## Vì sao quan trọng

Thử lại với [exponential backoff](https://broadrouter.com/vi/glossary/exponential-backoff/) là cách làm chuẩn, và nhiều SDK tự động thử lại. Không có idempotency, một lần thử lại sau timeout có thể tạo ra hai đơn hàng hoặc hai lần trừ tiền. Có key, việc thử lại là an toàn bất kể lần đầu đã làm gì. Vì vậy đây là công cụ cốt lõi cho agent và script mua, đặt chỗ hay tạo thứ gì đó mà không có người theo dõi.

## Trên BroadNet Inference

BroadNet dùng mẫu này cho việc mua [key theo giờ](https://broadrouter.com/vi/blog/hourly-llm-api-key-explained/). `POST /portal/keys/hourly` nhận `request_id` trong body JSON, và tài liệu ghi rằng “Idempotency is required for money safety” (Bản dịch: idempotency là bắt buộc để an toàn về tiền):

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

Dùng lại một `request_id` không tạo hay tính tiền thêm key nào. Sau timeout, mất kết nối, 409 `mint_in_progress` hoặc lỗi 5xx, hãy thử lại với cùng `request_id`. Lần gửi lại trả về `already_issued: true` và alias của key; chỉ phản hồi thành công đầu tiên mới chứa key gốc. Tài liệu viết: “Never generate a replacement id until the original result is known.” (Bản dịch: đừng bao giờ tạo id thay thế cho tới khi biết kết quả ban đầu.)

BroadNet không ghi nhận idempotency key cho `/v1/chat/completions` hay transcription. Xem [mã lỗi và thử lại](https://broadrouter.com/vi/guides/errors-and-retries/) để biết nên thử lại gì ở đó, và [rate limit](https://broadrouter.com/vi/glossary/rate-limit/) để hiểu vì sao thử lại mù quáng có thể làm lỗi 429 tệ hơn.

## Câu hỏi thường gặp

### Khi nào nên tạo idempotency key mới?

Chỉ khi có một hành động mới. Hãy dùng lại cùng một key cho mọi lần thử lại của một hành động, và đừng tạo key mới cho tới khi biết kết quả của lần thử đầu.

### Request chat completion của LLM có cần idempotency key không?

Việc sinh văn bản không để lại tác động lâu dài, nên một request chat bị lặp thường chỉ tốn token thêm lần nữa. Key quan trọng với các lệnh gọi trừ tiền hoặc tạo tài nguyên. BroadNet chỉ ghi nhận nó cho việc mua key theo giờ, không cho chat completion.

### Điều gì xảy ra nếu dùng lại key với body request khác?

Bản thảo của IETF nói server nên từ chối với 422 Unprocessable Content, vì key đó đã gắn với một request khác.

## Xem thêm

-   [Exponential backoff (lùi thời gian theo cấp số nhân)](https://broadrouter.com/vi/glossary/exponential-backoff/) (thuật ngữ)
-   [Giới hạn tần suất (rate limit)](https://broadrouter.com/vi/glossary/rate-limit/) (thuật ngữ)
-   [API key (khóa API)](https://broadrouter.com/vi/glossary/api-key/) (thuật ngữ)
-   [Concurrency (request đồng thời)](https://broadrouter.com/vi/glossary/concurrency/) (thuật ngữ)
-   [Mã lỗi BroadNet Inference và khi nào nên thử lại](https://broadrouter.com/vi/guides/errors-and-retries/) (hướng dẫn)
-   [Khóa API key vào server của bạn bằng danh sách IP cho phép](https://broadrouter.com/vi/guides/api-keys-ip-allow-lists/) (hướng dẫn)
-   [Agent chạy dài: timeout, retry và checkpoint đứng vững](https://broadrouter.com/vi/blog/long-running-agents-timeouts-retries/) (bài viết)
-   [API key LLM theo giờ: giá cố định mỗi giờ, giải thích rõ](https://broadrouter.com/vi/blog/hourly-llm-api-key-explained/) (bài viết)

Hãy thử với khối lượng công việc thực tế của bạn. Tài khoản mới được tặng US$5 tín dụng ban đầu cho Gemma và chuyển giọng nói thành văn bản. DeepSeek, GLM và Qwen3.8 cần nạp tiền.

[Bắt đầu](https://inference.broadnet.ai/account/?utm_source=broadrouter&utm_medium=referral&utm_campaign=vi-glossary-idempotency-key&utm_content=page-cta) ·

**Nguồn**

-   [IETF HTTPAPI, The Idempotency-Key HTTP Header Field (bản thảo Internet-Draft)](https://datatracker.ietf.org/doc/draft-ietf-httpapi-idempotency-key-header/)
-   [AWS Builders' Library, timeout, thử lại và backoff kèm jitter (idempotency token)](https://builder.aws.com/content/3EumjoZascWd1oZiEgL8ORlv3qE/timeouts-retries-and-backoff-with-jitter)
-   [Tài liệu tham chiếu API BroadNet Inference, key theo giờ (idempotency bằng request\_id) (tiếng Anh)](https://inference.broadnet.ai/docs?utm_source=broadrouter&utm_medium=referral&utm_campaign=vi-glossary-idempotency-key&utm_content=sources#hourly-keys)
