Clave de idempotencia
Envía una clave de idempotencia con las peticiones de la API System One para reintentar decisiones sin doble cobro de créditos.
La clave de idempotencia identifica una operación lógica de la API System One. Si generas una clave nueva para cada operación y la reutilizas en cada reintento de esa misma operación, puedes recuperar un resultado después de un timeout o de un error de red sin lanzar otra evaluación ni volver a cobrar créditos. Evaluar a propósito la misma entrada otra vez es una operación nueva, no un reintento.
Preguntas frecuentes
Q: ¿Qué es una clave de idempotencia en la API System One? A: Un token generado por el cliente. Los reintentos devuelven el mismo resultado de decisión sin cobrar créditos dos veces.
Q: ¿Cuándo enviarla? A: Siempre que el cliente pueda reintentar la misma decisión lógica tras timeout, error de red o 5xx.
Preguntas frecuentes
¿Qué es una clave de idempotencia en la API System One?
Un token generado por el cliente. Los reintentos devuelven el mismo resultado de decisión sin cobrar créditos dos veces.
¿Cuándo enviarla?
Siempre que el cliente pueda reintentar la misma decisión lógica tras timeout, error de red o 5xx.
Por qué usar una clave de idempotencia
Sin una clave de idempotencia, repetir una petición es una evaluación aparte: puede devolver otra respuesta y puede cobrar créditos otra vez. Con una clave, la segunda petición no vuelve a ejecutar la decisión, sino que devuelve el resultado ya registrado.
La clave se genera una sola vez, antes del primer envío, y se guarda junto con la petición completa. No uses una clave global de entorno, una constante compartida entre trabajos ni un hash del contenido: contenido idéntico puede pertenecer a evaluaciones distintas y facturables.
| Situación | Clave de operación y petición |
|---|---|
| Decisión o trabajo nuevo | Crea un UUID nuevo y una petición completa. |
| Evaluar a propósito la misma entrada otra vez | Crea un UUID nuevo aunque el cuerpo de la petición sea idéntico: es una operación facturable nueva. |
Reintento tras timeout, respuesta perdida o request_in_progress | Reutiliza la clave de la operación existente y la petición completa sin cambios; respeta cualquier retardo indicado. |
| Recuperación tras un fallo o reinicio de la aplicación | Carga la operación completa guardada de forma durable antes del primer envío; no vuelvas a crearla. |
| Usar otra clave de API de la misma cuenta | Conserva la misma clave de operación para la recuperación: cambiar de credenciales no crea un espacio de nombres aparte. |
Cómo enviar la clave
La cabecera Idempotency-Key es un encabezado de petición opcional. Envíala en cada operación:
POST /v1/systemone
Authorization: Bearer $SYSTEM_ONE_API_KEY
Content-Type: application/json
Idempotency-Key: 3f7c1a52-9c1e-4b8d-8a41-2d5b6e7f9a01El valor debe cumplir el patrón ^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$, es decir, entre 1 y 128 caracteres. Un valor inválido devuelve HTTP 422 con el código invalid_idempotency_key.
Las claves tienen alcance de cuenta: valen para todas las claves de API de esa cuenta y para su Playground de sesión. Otras cuentas tienen espacios de nombres separados.
La clave nunca se envía hacia el proveedor del modelo: es un mecanismo de la API System One.
Enviar la clave desde el SDK
El SDK no genera una clave de idempotencia automáticamente, ni el transporte Fetch. Pásala en la cabecera de la llamada:
const result = await client.evaluate(request, {
headers: { 'Idempotency-Key': key },
});Para que la recuperación sobreviva a un reinicio, guarda la clave y la petición completa en tu propio registro de trabajo antes del primer envío. Después de un fallo, carga ese registro en lugar de crear un UUID nuevo o reconstruir la petición. No generes una clave nueva dentro del código de reintento: puede provocar otro cobro.
Reenvío frente a recálculo
Cuando la API recibe una clave conocida junto con la misma petición, devuelve la respuesta original sin cambios: mismo estado, mismo texto y las cabeceras permitidas. No hay una segunda evaluación del modelo ni un segundo cargo de créditos. La respuesta incluye la cabecera X-Idempotency-Replayed: true.
Un reenvío correcto sigue consumiendo la cuota de la plataforma, pero no añade ningún cargo nuevo.
La comparación usa la petición canónica validada, incluido el modelo efectivo, el contexto, las preguntas, los criterios y los campos de extensión aceptados. El orden de las claves de un objeto y el formato de los espacios en blanco no influyen; el orden de los arrays, los valores de los campos y la diferencia entre un campo null y uno omitido sí influyen. Una petición distinta con la misma clave devuelve 409 idempotency_conflict.
Envía y guarda siempre un model explícito. Si una petición anterior omitió el modelo, conserva el modelo efectivo original cuando recuperes la operación.
Las imágenes forman parte de la identidad de la petición: cada cadena base64, tipo de medio y orden de los elementos. Reordenar o reemplazar una imagen bajo la misma clave guardada produce un conflicto.
La ventana de 24 horas
Las operaciones completadas se pueden recuperar con su clave durante 24 horas desde la creación de la petición. Pasado ese plazo, la misma clave puede iniciar una operación nueva y facturable; puede que no devuelva ningún error de clave expirada. Esta ventana no es una protección permanente contra duplicados.
Sin clave de operación, repetir una petición es una evaluación separada. Guarda las respuestas importantes en tu propia aplicación en lugar de depender del reenvío como acceso a largo plazo.
Errores de idempotencia
| Código | HTTP | Qué significa |
|---|---|---|
invalid_idempotency_key | 422 | El valor de la clave no cumple el formato permitido. |
idempotency_conflict | 409 | La misma clave se usó con un cuerpo de petición distinto. Restaura el cuerpo original o usa una clave nueva para una operación realmente diferente. |
request_in_progress | 409 | La operación sigue en curso. La respuesta incluye Retry-After: espera y reintenta con la misma clave y el mismo cuerpo. |
idempotency_failed | 409 | La operación anterior falló y sus créditos fueron devueltos. Usa una clave nueva solo para un intento nuevo deliberado. |
request_expired | 409 | La reserva de créditos caducó durante la operación. |
idempotency_expired | 410 | Los datos de reenvío ya no están disponibles. Consulta la operación original antes de empezar otra. |
Errores comunes
- Generar una clave nueva en cada reintento. Cada clave nueva es una operación nueva y facturable. Reutiliza la clave guardada de la operación original.
- Reutilizar una clave con un cuerpo distinto. Si cambias el cuerpo, la API responde
409 idempotency_conflict. Guarda la petición completa y envíala sin cambios. - Guardar la clave solo en memoria. Si el proceso se reinicia, la operación se pierde. Persiste la clave y la petición completa antes del primer envío.
- Tratar la ventana de 24 horas como protección permanente. Pasado ese plazo la misma clave puede iniciar una operación nueva y facturable.
Para seguir: referencia de la API, errores de la API, versionado de la API, facturación y créditos y SDK.