BroadRouter
Magsimula

Idempotency key

Na-update

Ang idempotency key ay natatanging value, kadalasang random na ID gaya ng UUID, na ikinakabit ng client sa request na nagbabago ng state, gaya ng bayad o pagbili. Kapag ipinadala ulit ang parehong request gamit ang parehong key, ibinabalik ng server ang orihinal na resulta sa halip na gawin ulit ang aksyon.

Tinatawag ding: Idempotency-Key header, idempotency token, idempotent request, idempotent retry, ligtas na retry

Sa pinakamasamang sandali pumapalya ang network: pagkatapos kumilos ng server pero bago mo natanggap ang sagot. Ginagawang ligtas ng idempotency key ang retry.

Paano ito gumagana

Gumagawa ang client ng natatanging key para sa isang sinasadyang aksyon at ipinapadala ito kasama ng request. Itinatago ng server ang key kasama ng resulta. Kapag dumating ulit ang parehong key, ibinabalik ng server ang naka-store na resulta sa halip na kumilos ulit.

Ginagawang standard ito ng IETF HTTPAPI working group bilang request header na Idempotency-Key (draft 08, Oktubre 2026, hindi pa RFC). Inilalarawan nito ang key bilang “a unique value generated by the client which the resource uses to recognize subsequent retries of the same request” (Salin ng BroadRouter: “isang natatanging value na gawa ng client na ginagamit ng resource para makilala ang mga susunod na retry ng parehong request”) at inirerekomenda ang UUID o katulad na random na ID. Ang mga error case ng draft:

Sitwasyon Status
Walang key kung saan ito kailangan 400 Bad Request
Tumatakbo pa ang orihinal na request 409 Conflict
Ginamit ulit ang key sa ibang body 422 Unprocessable Content

Ganito rin ang punto ng Builders’ Library ng AWS mula sa panig ng client: “APIs with side effects aren’t safe to retry unless they provide idempotency.” (Salin ng BroadRouter: “Hindi ligtas i-retry ang mga API na may side effect maliban kung may idempotency ang mga ito.”)

Bakit ito mahalaga

Standard na practice ang retry na may exponential backoff, at maraming SDK ang awtomatikong nagre-retry. Kung walang idempotency, puwedeng makagawa ng dalawang order o dalawang singil ang retry pagkatapos ng timeout. Kapag may key, ligtas ang retry anuman ang ginawa ng unang subok. Kaya pangunahing tool ito ng mga agent at script na bumibili, nagbu-book o gumagawa ng mga bagay nang walang taong nagbabantay.

Sa BroadNet Inference

Ginagamit ng BroadNet ang pattern na ito sa pagbili ng hourly key. Tumatanggap ang POST /portal/keys/hourly ng request_id sa JSON body, at sinasabi ng docs na “Idempotency is required for money safety” (Salin ng BroadRouter: “Kailangan ang idempotency para sa kaligtasan ng pera”):

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

Hindi gumagawa o naniningil ng panibagong key ang paggamit ulit ng request_id. Pagkatapos ng timeout, naputol na connection, 409 mint_in_progress o 5xx, mag-retry gamit ang parehong request_id. Ang replay ay nagbabalik ng already_issued: true at ng alias ng key; ang unang matagumpay na response lang ang may raw key. Sabi ng docs: “Never generate a replacement id until the original result is known.” (Salin ng BroadRouter: “Huwag kailanman gumawa ng kapalit na id hangga’t hindi alam ang orihinal na resulta.”)

Walang idinodokumentong idempotency key ang BroadNet para sa /v1/chat/completions o sa transcriptions. Tingnan ang mga error code at retry para sa kung ano ang dapat i-retry doon, at ang rate limits para sa kung bakit puwedeng palalain ng bulag na retry ang 429.

Mga tanong

Kailan ako dapat gumawa ng bagong idempotency key?

Para lang sa bagong aksyon na sinasadya mo. Gamitin ang parehong key sa bawat retry ng iisang aksyon, at huwag gumawa ng bago hangga't hindi mo alam ang resulta ng unang subok.

Kailangan ba ng idempotency key ang mga LLM chat completion request?

Walang pangmatagalang side effect ang pag-generate ng text, kaya kadalasan ay token lang ulit ang gastos ng inulit na chat request. Mahalaga ang key sa mga call na naniningil ng pera o gumagawa ng resource. Sa pagbili lang ng hourly key ito idinodokumento ng BroadNet, hindi sa chat completions.

Ano ang mangyayari kung gagamitin ko ulit ang key sa ibang request body?

Ayon sa IETF draft, dapat itong tanggihan ng server gamit ang 422 Unprocessable Content, dahil nakatali na ang key sa ibang request.

Basahin bilang MarkdownTanungin ang ChatGPTTanungin ang ClaudeTanungin ang Perplexity