Límites de uso

Hay dos límites y acotan cosas distintas. Uno cuenta peticiones; el otro
cuenta habitaciones. Un cupo por minuto no dice nada sobre cuánto calendario ha
consumido una key, y por eso existe el segundo.

El límite de peticiones

Las peticiones se limitan por key, por minuto. El cupo lo fija el hotel que
emitió la key; el valor por defecto son 60 peticiones por minuto.

Excederlo devuelve 429:

{ "message": "Too Many Attempts." }

Esta respuesta no trae error_code. Hay que comparar contra el estado
429 — un manejador que se guíe por error_code va a caer a la rama genérica.

Cómo esperar

Hay que esperar y reintentar. Un backoff exponencial con jitter es la forma
correcta: un intervalo de reintento fijo en varios workers propios los vuelve a
sincronizar en la misma ráfaga que causó el límite.

Para POST /bookings, hay que reintentar con el mismo
Idempotency-Key, para que el reintento no pueda crear
una segunda reserva.

Diseñar para no chocar con él

La mayoría de las integraciones que chocan con el límite están sondeando algo que
podrían haber pedido una sola vez:

• Cachear el catálogo. GET /properties y GET /units cambian cuando el
  hotel edita su configuración — o sea, rara vez. Conviene traerlos en un
  calendario, no por cada vista de página.
• Pedir una ventana, no un día. GET /rates cotiza un
  rango de fechas entero en una llamada, y unit_ids lo estrecha. Treinta
  llamadas de un día hacen el mismo trabajo treinta veces.
• Usar /quote para una estadía, no /rates filtrado hasta ella.
• Paginar con un per_page sensato. El tope es 200; el valor por defecto,
  50. Paginar un catálogo grande de 10 en 10 gasta el cupo en sobres.

Hay además un límite por IP sin autenticar delante de la autenticación, así que
las peticiones que ni siquiera logran autenticarse también quedan limitadas.

Los techos de inventario

Separado de todo lo anterior, cada key tiene un tope de cuánto inventario
puede consumir. Los fija el hotel, igual que el cupo por minuto:

Al toparlos, POST /bookings responde 429 con código y con números:

{
  "message": "This API key is already holding its maximum of 25 rooms.",
  "error_code": "KEY_HOLD_LIMIT_REACHED",
  "limit": 25,
  "used": 25
}

Éste sí trae error_code, a diferencia del 429 de peticiones por minuto.
Si tu manejador de 429 ramifica sólo por estado, va a tratar los dos igual —
y las recuperaciones no son la misma.

La recuperación tampoco es esperar sin más:

• Contra KEY_BOOKING_QUOTA_EXCEEDED sí se espera: la ventana es móvil, así que
  el cupo se va liberando a medida que envejecen las reservas más viejas.
• Contra KEY_HOLD_LIMIT_REACHED hay algo que hacer ahora: confirmar un hold
  o cancelarlo libera el cupo de inmediato. Dejar que venza solo también, pero
  tarda lo que le quede de reloj.

Una integración que devuelve inventario que no va a usar rara vez ve este
segundo techo. Ver Holds.

Por qué existen los techos

No son una cuota comercial. Una API key vive en el servidor de un tercero, y
tarde o temprano alguna se filtra. El cupo por minuto no protege un calendario:
a 60 peticiones por minuto se puede tapizar el libro de un hotel en una tarde sin
excederlo nunca. Los techos acotan el daño en la unidad que importa —
habitaciones — y le dan al hotel un número que puede subir para tu integración
sin subírselo a todo el mundo.

Si tu integración es legítima y tropieza con un techo, el hotel puede
ajustárselo a tu key en concreto.

Relacionado

• Paginación — cómo recorrer una colección de forma eficiente.
• Holds — cómo retener una habitación sin venderla, y cómo
  devolverla.
• Errores — las dos clases de 429, en contexto.