Guías

Idempotencia

En esta página

Una llamada puede fallar sin que sepas si llegó al servidor: un timeout, un corte de red. Si la repites a ciegas, puedes crear la misma tarea dos veces. La idempotencia evita ese duplicado.

Crear tareas: Idempotency-Key

POST /tasks acepta la cabecera opcional Idempotency-Key. Si repites la petición con la misma clave, recibes la tarea original en vez de una nueva, también con 201.

bash

curl -s -X POST https://system.secretar-ia.org/api/v1/tasks \
  -H "Authorization: Bearer $SECRETARIA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 6f1c2b7e-5a4d-4e8f-9b3a-2d1c0e7f8a9b" \
  -d '{"title": "Revisar informe mensual"}'

Usa un valor único por cada operación lógica: un UUID o un id estable de tu propio sistema (por ejemplo, el id del registro que origina la tarea).

La clave se compara por persona: las claves de otras cuentas no chocan con las tuyas.
No caduca: si la reutilizas semanas después, sigues recibiendo la tarea original.
Formato: hasta 128 caracteres ASCII imprimibles, sin espacios. El prefijo local: está reservado. Un valor no válido responde 422 invalid_idempotency_key.

Cuidado

El cuerpo no se compara. Si reutilizas una Idempotency-Key con un cuerpo distinto, recibes la tarea original, sin cambios, y no se crea una nueva.

Crear proyectos: por nombre

POST /projects es idempotente por nombre. Si ya tienes un proyecto con ese name exacto, recibes el existente (con 201) y el resto de campos que envíes se ignoran: no se actualiza nada.

Borrar

DELETE /tasks/{id} repetido responde 404 la segunda vez, porque la tarea ya no existe. Si reintentas un borrado, trata ese 404 como un borrado correcto.