Escrituras que modifican un recurso existente
No interviene ninguna cabecera. Donde antes una repetición devolvía un error, ahora devuelve el estado actual:
Una repetición no escribe nada y su respuesta incluye
Idempotent-Replayed: true: esa cabecera es la que te permite distinguir entre “lo cancelé yo” y “ya estaba cancelado”.
Tres excepciones devuelven 409 en su lugar:
- Activar con un
activated_atdistinto. La hora de recogida es la que figura en el informe del laboratorio, así que un reintento no debe sobrescribirla silenciosamente. - Cancelar una cita ya cancelada con un
cancellation_reasondistinto. Mismo razonamiento: el motivo registrado puede haberse corregido desde entonces y un reintento no debe sobrescribirlo. Vuelve a enviar el motivo registrado u omítelo. - Cancelar pasado el punto de no retorno — una extracción de sangre confirmada, un envío recogido, un kit enviado o activado.
- Confirmar extracción de sangre — una segunda llamada devuelve
409. - Enviar resultados por email (
POST /v1/appointments/{id}/results/email) y Enviar resultados por email (POST /v1/home-kit-orders/{id}/results/email) — cada llamada envía un email. Un reintento tras un timeout o un5xxpuede enviar un duplicado al cliente.
Escrituras que crean algo
Cinco endpoints aceptan una cabecera opcionalIdempotency-Key, de 255 caracteres como máximo:
Una clave, cuatro intentos, un pedido: lo que recibes depende de cuándo reintentas y de si el cuerpo coincide:
- Misma clave, mismo cuerpo → durante 24 horas recibes de vuelta la respuesta original, marcada con
Idempotent-Replayed: true. El orden de los campos y los espacios en blanco no importan. - Misma clave, cuerpo distinto →
409. - Un
Idempotency-Keyvacío →400, en lugar de ignorarse.
Cuándo se libera la clave
La creación no es atómica: un5xx no significa que no se haya escrito nada.
- La solicitud falló antes de crear nada → la clave se libera, así que puedes reintentar con ella.
- La solicitud falló después de crear algo, o nunca devolvió respuesta → la clave sigue reservada y los reintentos reciben
409. Consulta el recurso para comprobar si existe y, si no existe, usa una clave nueva.
Una repetición devuelve el cuerpo de la respuesta registrado cuando se creó el recurso: una
instantánea, no una lectura en tiempo real. Si el recurso ha cambiado desde entonces, consúltalo
directamente.
Algunas creaciones también tienen una clave natural
Dos endpoints rechazan duplicados por sí solos, independientemente de cualquier cabecera:- Crear cita permite una cita por perfil, ubicación e instante. Una repetición devuelve
409con elappointment_idexistente. - Crear perfil devuelve
409cuandoemailya tiene un perfil. Si omitesemail, se genera un valor provisional único por solicitud, por lo que las repeticiones sí crean perfiles distintos.
409 que verás es el de la clave natural, y solo ese incluye el campo adicional (appointment_id o un discriminador error_name): un 409 de idempotencia solo incluye error, así que lee esos campos de forma defensiva.