Errores

Casi todos los errores llevan un código estable, legible por máquina:

{
  "message": "Not found.",
  "error_code": "NOT_FOUND"
}

Hay que comparar contra error_code. message es prosa escrita para una
persona y se puede reescribir en cualquier momento sin aviso. Ramificar sobre él
se va a romper.

Los errores de validación no traen error_code

Esta es la excepción que agarra a la gente desprevenida. Una falla corriente de
validación de campos devuelve 422 con otra forma — un message y un objeto
errors por campo, y ninguna llave error_code:

{
  "message": "The start field is required. (and 1 more error)",
  "errors": {
    "start": ["The start field is required."],
    "end": ["The end field is required."]
  }
}

Hay que leer errors, no message — message es genérico y no trae nada
accionable.

Así que un 422 puede tener cualquiera de las dos formas. Conviene revisar
primero si hay error_code y, si no, caer a errors.

Los códigos

Credenciales

Direccionamiento

No existe un NOT_FOUND genérico en esta API. Cada 404 nombra qué fue lo que
no se encontró, para que un manejador pueda distinguir "el id de habitación está
mal" de "el id de reserva está mal" sin leer prosa.

Crear una reserva

Confirmar y cancelar

Ni confirm ni cancel necesitan Idempotency-Key: son idempotentes por
estado. Reenviar el mismo confirm a una reserva ya confirmada, o el mismo
cancel a una ya cancelada, devuelve 200 con el mismo cuerpo. Un reintento
después de una respuesta perdida es el caso normal, no un error.

Por qué no se pudo vender la estadía

Todos responden 422 salvo UNIT_NOT_AVAILABLE, que en POST /bookings es
409: la habitación estaba libre al cotizar y dejó de estarlo. Son los que más
seguido va a ver una integración real.
Llevan además los números detrás del rechazo, que son la parte accionable: un
motor de reservas puede decir "mínimo 3 noches" en vez de "no se pudo reservar".

{
  "message": "This rate plan has a 3 night minimum stay.",
  "error_code": "RATE_PLAN_MIN_STAY",
  "min_stay": 3,
  "nights": 2
}

El objeto hay que tratarlo como abierto: qué campos extra vienen depende del
motivo, así que se leen los que uno reconozca y se ignora el resto.

La hora de corte

Un hotel puede fijar una hora de corte: a partir de esa hora, en su propio
reloj, deja de aceptar llegadas para ese mismo día. Pasada la hora,
POST /quote y POST /bookings responden 422 BOOKING_CUTOFF_PASSED para
cualquier estadía cuyo start_date sea hoy:

{
  "message": "The property stopped taking same-day bookings at 20:00.",
  "error_code": "BOOKING_CUTOFF_PASSED",
  "property_today": "2027-03-01",
  "cutoff_time": "20:00"
}

• "Hoy" es el día del hotel, no el tuyo ni el UTC. property_today dice
  cuál es, y cutoff_time es la hora local del hotel en formato HH:MM.
• Mañana se sigue vendiendo. Lo que corresponde es ofrecer la estadía a
  partir de property_today + 1, no reintentar.
• GET /availability ya lo refleja: una consulta que empieza hoy, pasada la
  hora de corte, devuelve cada unidad con available: false y
  remaining_capacity: 0.
• Un hold creado antes de la hora de corte se respeta. El corte se revisa al
  crear la reserva, no al confirmarla, así que confirm nunca responde este
  código. Ver Holds.

Límites de uso

Hay dos clases de 429 y no se comportan igual.

Un 429 de límite de peticiones — la cuota por minuto de tu key, o el techo
anónimo por IP — no trae error_code. Contra ése hay que comparar el
estado.

Un 429 de techo de inventario sí lo trae, y además dice cuánto:

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

Los dos traen Retry-After. Ver Límites de uso.

Webhooks

Una URL insegura — no https, o que resuelve a una dirección privada — no
tiene código propio: es un error de validación sobre url, con la forma de
errors de arriba.

Propiedad en hibernación

Un hotel puede poner una propiedad en hibernación durante su temporada baja.
Mientras dure, toda operación sobre esa propiedad responde 403, sea cual
sea el plan de hibernación que eligió el hotel. Las reservas existentes se
conservan; simplemente no se pueden leer ni cambiar desde esta API hasta que el
hotel la reactive.

Reintentar no sirve. Lo que corresponde es dejar de sincronizar esa
propiedad, avisarle a quien opera la integración y retomarla cuando las llamadas
dejen de responder 403. GET /properties la sigue listando: es la única
lectura que no apunta a una propiedad concreta.

El "no encontrado" dice qué, no dice por qué

El código nombra qué tipo de cosa no se encontró — habitación, plan, huésped,
reserva, propiedad. Lo que deliberadamente no distingue es por qué, y dentro
de cada tipo un 404 cubre tres situaciones:

• el recurso no existe;
• existe pero pertenece a otra propiedad;
• existe y no está expuesto a esta API.

Distinguirlas le permitiría a quien llama mapear la cuenta de otro sondeando ids.
Por eso UNIT_NOT_FOUND responde igual para una habitación inventada que para una
del hotel de al lado.

Cuando llega un 404 inesperado sobre un id en el que uno cree, lo primero que
hay que revisar no es si el registro existe — es si la habitación tiene un plan
tarifario activo del canal api y si uno está apuntando a la propiedad correcta.

Relacionado

• Autenticación y API keys
• Idempotencia
• Límites de uso
• Recibir eventos por webhook