Solicitudes idempotentes

Una solicitud puede fallar cuando Sursa ya ha hecho el trabajo: la conexión se corta o su proceso se reinicia antes de que llegue la respuesta. Si vuelve a enviar el mismo POST, podría crear una segunda tarjeta o un segundo webhook. Una clave de idempotencia lo evita.

Envíe un encabezado Idempotency-Key con cada POST y PATCH. Si Sursa ya ha recibido una solicitud con esta clave, no vuelve a ejecutar la operación: devuelve la respuesta que guardó la primera vez.

curl -X POST https://api.sursa.com/v1/cards/text \
  -H "Authorization: Bearer $SURSA_API_KEY" \
  -H "Idempotency-Key: 6f1d2c9e-7b0a-4c43-9a51-0d6c1c1f8e21" \
  -H "Content-Type: application/json" \
  -d '{"title": "Refund policy", "body_markdown": "Refunds are processed within 14 days."}'

Una solicitud repetida recibe el mismo estado y el mismo cuerpo que la primera, con un encabezado adicional:

HTTP/1.1 200 OK
Idempotency-Replayed: true
X-Request-Id: 01JB7R…

La solicitud repetida tiene su propio X-Request-Id.

Elegir una clave

Use un valor aleatorio nuevo, como un UUID v4, para cada operación lógica: «crear esta tarjeta», «registrar este webhook». Use el mismo valor en cada reintento de esa operación y nunca en otra distinta.
Una buena clave se deriva de sus propios datos cuando los tiene, por ejemplo sync-2026-10-24-record-1042. Así, incluso un trabajo reiniciado que ha perdido su memoria vuelve a enviar la misma clave.
La clave tiene de 1 a 255 caracteres ASCII imprimibles. Cualquier otra cosa devuelve 400 con el código api.idempotency_key_invalid.

Qué hace Sursa con la clave

Situación	Respuesta
Primera solicitud con esta clave	La operación se ejecuta de la forma habitual.
Misma clave, misma solicitud, la primera terminó con `2xx` o `4xx`	La respuesta guardada, con `Idempotency-Replayed: true`. La operación no se vuelve a ejecutar.
Misma clave, la primera solicitud sigue en curso	`409` `api.idempotency_in_progress` con `Retry-After: 1`. Espere y vuelva a intentarlo.
Misma clave, pero otro método, otra ruta, otro `Content-Type` u otro cuerpo	`409` `api.idempotency_mismatch`. La clave ya la usa otra solicitud.
La primera solicitud terminó con `5xx` o `429`	La clave se libera: la siguiente solicitud con ella vuelve a ejecutar la operación.

Una clave es válida durante 24 horas. Después, la misma clave inicia una operación nueva.
Las claves son independientes para cada organización y para cada quien llama a la API: dos claves de API distintas pueden usar el mismo valor sin afectarse entre sí.
También se guarda una respuesta de error 4xx. Una solicitud que no superó la validación falla de la misma manera cuando se repite con la misma clave; corríjala y envíela con una clave nueva.

Qué solicitudes la necesitan

Método	Idempotency-Key
`POST`, `PATCH`	Envíela. Cada endpoint que guarda su respuesta para una repetición incluye el encabezado en la referencia de la API.
`GET`, `PUT`, `DELETE`	No hace falta: por su significado, estos métodos se pueden repetir sin riesgo. El encabezado se acepta y no tiene efecto.
`POST` que solo lee, como la búsqueda, los informes financieros y `POST /v1/catalog/resolve`	Se acepta, pero no se guarda nada: la solicitud simplemente se vuelve a ejecutar.

Algunas operaciones se pueden repetir sin riesgo incluso sin el encabezado:

PUT /v1/cards-by-external-id/{external_id} crea o sustituye la tarjeta con su ID; una repetición con el mismo contenido no cambia nada.
Los documentos de una fuente personalizada se identifican por su external_id; si vuelve a enviar el mismo documento, se devuelve unchanged.
La respuesta del asistente que transmite POST /v1/chat usa el campo request_id del cuerpo en lugar del encabezado. Consulte Crear un bot de preguntas y respuestas.

Reintentar sin riesgo

Combine la clave con las reglas de reintento de Errores: cree la clave una vez, antes del primer intento, y envíela con cada intento de la misma operación.