Las redes fallan en el peor momento: después de que el servidor actúe, pero antes de que usted reciba la respuesta. Una clave de idempotencia hace que el reintento sea seguro.
Cómo funciona
El cliente crea una clave única para una acción prevista y la envía con la solicitud. El servidor guarda la clave junto con el resultado. Si vuelve a llegar la misma clave, el servidor reproduce el resultado guardado en lugar de actuar otra vez.
El grupo de trabajo HTTPAPI del IETF está estandarizando esto como la cabecera de solicitud Idempotency-Key (borrador 08, octubre de 2026, todavía no es un RFC). Describe la clave como “a unique value generated by the client which the resource uses to recognize subsequent retries of the same request” (traducción: un valor único generado por el cliente que el recurso usa para reconocer reintentos posteriores de la misma solicitud) y recomienda un UUID o un ID aleatorio similar. Los casos de error del borrador:
| Situación | Estado |
|---|---|
| Falta la clave donde es obligatoria | 400 Bad Request |
| La solicitud original sigue en curso | 409 Conflict |
| Clave reutilizada con otro cuerpo | 422 Unprocessable Content |
La Builders’ Library de AWS dice lo mismo desde el lado del cliente: “APIs with side effects aren’t safe to retry unless they provide idempotency.” (traducción: las APIs con efectos secundarios no son seguras de reintentar a menos que ofrezcan idempotencia).
Por qué importa
Los reintentos con backoff exponencial son práctica estándar, y muchos SDK reintentan automáticamente. Sin idempotencia, un reintento tras un timeout puede crear dos pedidos o dos cobros. Con una clave, reintentar es seguro sea cual sea el resultado del primer intento. Eso la convierte en una herramienta clave para agentes y scripts que compran, reservan o crean cosas sin una persona supervisando.
En BroadNet Inference
BroadNet usa este patrón para comprar claves por hora. POST /portal/keys/hourly recibe un request_id en el cuerpo JSON, y la documentación indica que “Idempotency is required for money safety” (traducción: la idempotencia es obligatoria para proteger el dinero):
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"}'
Reutilizar un request_id no crea ni cobra otra clave. Tras un timeout, una conexión caída, un 409 mint_in_progress o un 5xx, reintente con el mismo request_id. Una repetición devuelve already_issued: true y el alias de la clave; solo la primera respuesta correcta contiene la clave en bruto. La documentación dice: “Never generate a replacement id until the original result is known.” (traducción: nunca genere un ID de reemplazo hasta conocer el resultado original).
BroadNet no documenta una clave de idempotencia para /v1/chat/completions ni para transcripciones. Consulte códigos de error y reintentos para saber qué reintentar ahí, y límites de frecuencia para entender por qué los reintentos a ciegas pueden empeorar un 429.