Errores y límites

Los 7 status de una cotización

Una respuesta 200 siempre trae un status. Estos son los siete valores posibles y su código HTTP:

status	HTTP	Significado
ok	200	Se cotizó con éxito.
no_availability	200	Se consultó y ningún canal tiene tarifa. No es un error.
hotel_not_found	422	No podemos saber a qué hotel te refieres; hotel llega null.
not_quotable	422	Conocemos el hotel, pero ninguna fuente puede cotizarlo todavía (su mapeo espera revisión). Reintentar no cambia esto.
not_supported	422	El hotel está bien; este request no está respaldado por evidencia medida (hoy, la moneda: solo USD, EUR y MXN). A diferencia de not_quotable, tú puedes corregirlo cambiando el parámetro.
upstream_error	502	Falla de un canal externo. Nunca se disfraza de lista vacía.
overloaded	503	Nuestra propia cola rechazó la llamada antes de pedirle nada a nadie. No se cobra nada.

400 — request inválido

curl "https://api.rateshooter.com/v1/quotes?checkin=2026-12-11&checkout=2026-12-10&adults=2&hotel_id=2008" \
  -H "Authorization: Bearer <tu_api_key>"

{
  "status": "bad_request",
  "error": "checkout must be after checkin"
}

Falta identificar el hotel (ni hotel_id, ni hotel_ref, ni name):

{
  "status": "bad_request",
  "error": "Each hotel requires hotel_id, hotel_ref or name"
}

401 — autenticación

{
  "status": "unauthorized",
  "error": "Missing Authorization header. Use: Authorization: Bearer <api_key>"
}

{
  "status": "unauthorized",
  "error": "Invalid API key"
}

422 — grupo no cotizable por habitaciones

reason	Significado
rooms_insufficient	Las habitaciones pedidas no bastan para este grupo.
rooms_exceed_adults	Se pidieron más habitaciones que adultos.
party_not_quotable	Ningún número de habitaciones encaja.

{
  "status": "not_quotable",
  "reason": "rooms_insufficient",
  "min_rooms": 3,
  "max_rooms": 14,
  "message": "Este grupo necesita al menos 3 habitaciones"
}

min_rooms y max_rooms viajan siempre en este 422, sea cual sea el reason — así puedes mostrarle al usuario el rango válido sin adivinarlo.

429 — dos razones distintas

rate_limited es por segundo; quota_exceeded es por mes. Ambos responden 429, pero solo rate_limited trae Retry-After.

{
  "status": "rate_limited",
  "error": "Rate limit exceeded (10/s)"
}

Tomado del código, no capturado en producción.

{
  "status": "quota_exceeded",
  "error": "Monthly quota exhausted (98/100)"
}

Cabeceras de límite

Toda respuesta trae estas cabeceras, para que puedas llevar la cuenta de tu presupuesto sin adivinar:

Cabecera	Qué informa
ratelimit-limit	Tu límite por segundo, según tu plan.
ratelimit-remaining	Lo que te queda del burst (la ráfaga): una capacidad acumulada, no el límite por segundo — por eso puede ser mayor que ratelimit-limit.
ratelimit-reset	Segundos hasta que el burst se rellena por completo, al ritmo de tu límite por segundo.
retry-after	Solo en 429 rate_limited: segundos a esperar antes de reintentar.

Ejemplo real, justo al recibir un 429 rate_limited (misma captura de arriba): ratelimit-limit: 10, ratelimit-remaining: 0, ratelimit-reset: 12, retry-after: 1. El límite por segundo y el tamaño del burst dependen de tu plan — no asumas que son los mismos valores en todas las cuentas.

503 — nuestra cola, no un canal externo

Tomado del código, no capturado en producción.

{
  "status": "overloaded",
  "hotel": {
    "resolved_name": "Grand Oasis Cancun",
    "hotel_id": 2008,
    "verified": true
  },
  "offers": [],
  "meta": {
    "offers_count": 0,
    "billable": false
  },
  "stay": {
    "checkin": "2026-12-10",
    "checkout": "2026-12-11",
    "nights": 1,
    "adults": 2,
    "rooms": 1,
    "children": [],
    "currency": "USD"
  }
}

Retry-After: 5 viaja en los headers. Nada se cobra: X-HotelQuotes-Charged llega en 0. Ver qué se cobra y buenas prácticas para cómo reintentar.