Reference

Errors

One envelope, seven codes, a request_id on every one — and none of them are billed.

The envelope

{ "error": { "code": "source_unavailable", "message": "HTTP 403", "chain": "hyatt", "request_id": "a48cd3ce2b5f9b85" } }

code is one of the seven below, message is for a human, chain is present when a source was involved, and request_id echoes the edge’s ray id — quote it when reporting a problem and the call is traceable. Every error response carries X-Credits-Charged: 0.

Codes

HTTP	`code`	When
400	`invalid_request`	the body failed validation (a past check-in, 26 hotel codes, an unknown chain), or no such route
401	`auth_failed`	missing, malformed, revoked or unknown `x-api-key`
404	`hotel_not_found`	the chain does not recognise the property code
429	`quota_exceeded`	the account’s credits for the period are spent
429	`rate_limited`	over the plan’s requests per second; `Retry-After` says how long
503	`source_unavailable`	the chain or OTA refused or broke; the reason is sanitised, the full upstream message is in our log under `request_id`
504	`upstream_timeout`	the source never answered in time

Answers that are not errors

status: sold_out, closed and restricted_los (with min_los where the chain states it) are answers — the hotel exists and is not selling that stay. They are billed like any other result. In /parity, a channel with skipped set had no listing matched for the hotel or answered with an error; it is reported in its row and never charged.

Retrying

rate_limited: wait Retry-After seconds. source_unavailable and upstream_timeout: a retry a few seconds later often succeeds — a source under a velocity flag recovers in minutes — and costs nothing if it fails again. quota_exceeded: nothing to retry until the period resets or the plan changes; GET /v1/usage still answers.

Stay dates

A check-in already past in every timezone (earlier than yesterday UTC) is refused as invalid_request without an upstream call, because no chain sells a stay that has started and each one used to say so differently — three of them used to bill a sold_out for it.