BroadRouter
Comenzar

Clave de idempotencia (idempotency key)

Actualizado

Una clave de idempotencia es un valor único, normalmente un ID aleatorio como un UUID, que el cliente adjunta a una solicitud que cambia el estado, como un pago o una compra. Si la misma solicitud se envía de nuevo con la misma clave, el servidor devuelve el resultado original en lugar de ejecutar la acción dos veces.

También llamado: clave de idempotencia, cabecera Idempotency-Key, token de idempotencia, solicitud idempotente, reintento idempotente, idempotency key, Idempotency-Key header, idempotency token, idempotent request, idempotent retry

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.

Preguntas frecuentes

¿Cuándo debo generar una nueva clave de idempotencia?

Solo para una nueva acción prevista. Reutilice la misma clave en cada reintento de una acción y no cree una nueva hasta conocer el resultado del primer intento.

¿Las solicitudes de chat a un LLM necesitan una clave de idempotencia?

Generar texto no tiene efectos secundarios duraderos, así que repetir una solicitud de chat normalmente solo vuelve a costar tokens. La clave importa en llamadas que cobran dinero o crean recursos. BroadNet solo la documenta para comprar claves por hora, no para chat completions.

¿Qué pasa si reutilizo una clave con otro cuerpo de solicitud?

El borrador del IETF dice que el servidor debe rechazarla con 422 Unprocessable Content, porque la clave ya está vinculada a otra solicitud.

Leer en MarkdownPreguntar a ChatGPTPreguntar a ClaudePreguntar a Perplexity