Saltar al contenido principal

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_at distinto. 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_reason distinto. 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.
Tres endpoints no son seguros para reintentos de forma deliberada:

Escrituras que crean algo

Cinco endpoints aceptan una cabecera opcional Idempotency-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: Diagrama de secuencia: una solicitud duplicada enviada 350 ms después de la primera recibe un 409 mientras esa primera sigue en curso, la primera devuelve 201, un reintento posterior con la misma clave devuelve el mismo pedido marcado como Idempotent-Replayed y la misma clave con un cuerpo modificado devuelve 409. Diagrama de secuencia: una solicitud duplicada enviada 350 ms después de la primera recibe un 409 mientras esa primera sigue en curso, la primera devuelve 201, un reintento posterior con la misma clave devuelve el mismo pedido marcado como Idempotent-Replayed y la misma clave con un cuerpo modificado devuelve 409. Las claves están acotadas a tu API key y al endpoint, así que nunca colisionan con las de otro partner ni con la misma clave usada en otro sitio.
  • 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-Key vacío → 400, en lugar de ignorarse.

Cuándo se libera la clave

La creación no es atómica: un 5xx 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 409 con el appointment_id existente.
  • Crear perfil devuelve 409 cuando email ya tiene un perfil. Si omites email, se genera un valor provisional único por solicitud, por lo que las repeticiones sí crean perfiles distintos.
Cuando se aplican ambos, el 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.