Errores, límites y reintentos

400 — El cuerpo no es válido o X-Market-Id no es ningún mercado. Corrige la petición: reintentar igual da lo mismo.

401 — Clave ausente o no válida. Revisa la cabecera Authorization: Bearer o X-API-Key.

403 — La clave existe pero no opera en ese mercado, o la operación no es suya (cancelar la reserva de otra clave). Pide que se amplíe la clave; no reintentes.

404 — La reserva no existe. Comprueba el código de seguimiento.

409 — Horario no disponible, o la reserva ya no admite el cambio (hoja de ruta emitida, servicio en marcha). Ofrece otra hora al cliente; error dice el motivo.

422 — Trayecto fuera de ámbito, punto no reconocido o paradas que el régimen de tarifa no admite. Enseña el motivo de error al usuario: no es un fallo técnico.

429 — Límite de peticiones superado (120 por minuto y clave por defecto, compartido entre instancias). Espera los segundos de Retry-After y reintenta con espera creciente.

503 — La API no está habilitada en este entorno. Reintenta más tarde; si persiste, escríbenos.

Por defecto, 120 peticiones por minuto y clave, contadas entre todas las instancias. Frena el bucle descontrolado de una integración. Al superarlo, 429 con Retry-After en segundos.

Reintenta con espera creciente (1 s, 2 s, 4 s…) y solo ante 429, 408 o 5xx. Un 4xx distinto no se arregla insistiendo.

Si una llamada a POST /api/v1/reservas se corta sin respuesta, consulta antes de repetir: guarda en tu sistema tu referencia y compárala con las notas de la reserva. Repetir a ciegas puede crear dos.