Idempotency-Key

Todo método no seguro (POST, PUT, PATCH, DELETE) en las operaciones de /api/v1 con contexto de organización — es decir, las que se ejecutan dentro de una organización activa, como proyectos, defectos, casos de prueba, ejecuciones y planes — acepta una cabecera OPCIONAL Idempotency-Key. Envía la misma clave en un reintento y Probara reproduce la respuesta original en lugar de volver a ejecutar la mutación — útil para reintentos de red, timeouts del cliente y esos dobles clics donde no sabes si la petición llegó a enviarse. Las peticiones GET/HEAD ignoran la cabecera por completo.

Los endpoints de autenticación (/api/v1/auth/*), perfil de usuario (/api/v1/profile, /api/v1/profile/avatar) y subida de avatar de proyecto (/api/v1/projects/{projectId}/avatar) no admiten esta cabecera — se ignora en silencio.

Las subidas de archivos (cualquier petición con cuerpo multipart/form-data, como la preparación de adjuntos o la subida de evidencias de un defecto) también ignoran la cabecera: no se registra ni se reproduce nada. Solo las peticiones de preparación se pueden reintentar sin clave de forma segura, porque un archivo preparado que ninguna petición posterior referencia caduca por sí solo. La subida de evidencias de un defecto no es una preparación: un reintento puede guardar los mismos archivos dos veces, así que revisa la lista de adjuntos del defecto antes de reintentarla.

Las claves están limitadas por organización y por el miembro que actúa: el mismo valor de clave usado por otra organización, o por otro miembro dentro de la misma organización, se trata como una clave independiente y nunca reproduce una respuesta entre esos límites.

Formato de la clave

• No vacía
• No mayor de 255 caracteres ASCII visibles (sin espacios en blanco, caracteres de control ni puntos de código fuera de ASCII)

Una clave inválida responde 400 y el handler nunca se ejecuta.

Uso

# Primer intento — se ejecuta con normalidad y la respuesta queda registrada bajo la clave.
curl -sS -X POST \
  -H "Authorization: Bearer $PROBARA_API_TOKEN" \
  -H "Idempotency-Key: 8f14e45f-ceea-4a3c-b9a8-1a6b3d2f0e91" \
  -H "Content-Type: application/json" \
  -d '{"name":"Flujo de checkout"}' \
  "https://app.probara.net/api/v1/projects"

HTTP/1.1 201 Created
Content-Type: application/json

{ "ulid": "01J...PROJ", "name": "Flujo de checkout", ... }

Reintentar la petición idéntica con la misma clave y el mismo cuerpo dentro de la ventana de retención devuelve el mismo estado y cuerpo — sigue siendo 01J...PROJ, sin un segundo proyecto creado — con una cabecera adicional en la respuesta:

HTTP/1.1 201 Created
Idempotency-Replayed: true
Content-Type: application/json

{ "ulid": "01J...PROJ", "name": "Flujo de checkout", ... }

Semántica de la respuesta

Situación	Respuesta
Primera petición con una clave nunca vista	Se ejecuta con normalidad; la respuesta se registra para reproducirla (JSON, estado < 500, sin ser 204 ni binaria)
Reintento idéntico dentro de la ventana de retención	Mismo estado y cuerpo que el original, más Idempotency-Replayed: true
Llega un duplicado mientras la primera petición sigue en curso	409 con el envoltorio de error estándar (code: "conflict") y una cabecera Retry-After
Se reutiliza la misma clave con un método, ruta o cuerpo distinto	422 con code: "validation_failed"; no se ejecuta nada
Clave inválida (vacía o de más de 255 caracteres ASCII visibles)	400; no se ejecuta nada
La primera petición falla	Se libera la reserva de la clave; un reintento posterior con la misma clave se ejecuta con normalidad
La respuesta es 204, no es JSON o es binaria	Pasa sin registrarse — un reintento con la misma clave vuelve a ejecutar el handler

Retención

Los registros de clave se conservan durante 24 horas. Pasada esa ventana, la misma clave se comporta como una clave nueva, nunca vista: la petición idéntica vuelve a ejecutar el handler y Idempotency-Replayed no aparece en esa respuesta.

Errores

Estado	Código	Significado
400	validation_failed	Idempotency-Key está vacía o supera los 255 caracteres ASCII visibles
409	conflict	Hay una petición en curso con la misma clave; incluye una cabecera Retry-After
422	validation_failed	La clave ya se usó con un método, ruta o cuerpo de petición distinto

Relacionado

• Autenticación API — tokens Bearer y sesión
• Referencia API — paginación, errores, PATCH consolidado