BroadRouter
Bắt đầu

Idempotency key (khóa idempotency)

Cập nhật

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 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ờ. 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):

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 để biết nên thử lại gì ở đó, và 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.

Đọc dạng MarkdownHỏi ChatGPTHỏi ClaudeHỏi Perplexity