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.

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.

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