Price Recommendation API Errors and Warnings
An HTTP error means the request did not produce a successful recommendation response. A warning means the response succeeded with a limitation. Always inspect Calendar Prices warnings before treating a result as ready to publish.
Handle successful responses with warnings
| Warning code | Meaning | What your application can do |
|---|---|---|
| INCOMPLETE_CALENDAR | A calendar-dependent rule could not run: on every night because no calendar was sent, or on some nights because rows it needed were not sent (a neighboring night for gap and adjacent day, any date of a lead-time window for occupancy pacing). One entry per rule | Supply current availability, the nights around your bookings and every night of each occupancy window; do not invent availability |
Warnings include code, field (the rule that was skipped), and a human-readable message. When specific nights were affected, affected_date_count counts them across the full calculated calendar, including dates outside a requested start_date–end_date window; it is omitted when the whole calendar was missing.
Two things are deliberately not warnings. An end_date beyond the available calendar is clamped to the last available date; read coverage.end_date for the range you actually received, and never fill dates beyond it by repeating the last price. Nights without a usable local demand signal are priced with a 0% market-demand line and no warning.
Preserve unknown future warning codes and display their messages instead of failing deserialization. Your business policy can still require review before publishing. An empty warning array does not guarantee bookings, complete stay validity, or publication safety.
Handle failed requests
| HTTP status | Typical cause | Recovery |
|---|---|---|
| 400 | Malformed JSON; Base Price also uses this for some type or fee validation failures | Correct the request before retrying |
| 403 | API key/account authorization failure | Check credentials and account access |
| 413 | Calendar payload exceeds its supported size | Reduce the input to at most 1,000 calendar rows |
| 422 | Missing, invalid, incompatible, or unsupported values; Calendar Prices also uses this for wrong field types | Inspect validation details and correct the input |
| 429 | Gateway throttling | Honor Retry-After if present; otherwise use bounded backoff with jitter |
| 500 / 503 | Server or pricing-data availability problem | Use bounded retries; retain diagnostics and escalate persistent failures |
Invalid output dates
A start_date or end_date before today in the property's timezone returns
HTTP 422 with START_DATE_IN_PAST or END_DATE_IN_PAST in error.details. A
start_date after end_date returns INVALID_DATE_RANGE; a start_date after
the available calendar returns START_DATE_BEYOND_AVAILABLE_HORIZON. Empty or
invalid dates return INVALID_DATE_FORMAT; non-string, non-null inputs return
INVALID_FIELD_TYPE. Omitted or null boundaries return the full available
calendar. An end_date beyond available coverage is clamped to the available
calendar without a warning; coverage.end_date shows where the response stops.
Limits and prices that cannot be returned
For INVALID_PRICE_LIMITS in the validation details, compare the effective
bounds. Each omitted or null bound still has a default: 70% of base for the minimum
and 1000% for the maximum. A single explicit bound can conflict with the other
default; send both bounds when needed.
The top-level PRICE_BELOW_CURRENCY_MINIMUM code (HTTP 422) means a positive
final calculation rounded to zero. Review the affected date's base price, discounts,
and minimum limit before retrying. A nonpositive calculation instead returns
PRICING_DATA_UNAVAILABLE (HTTP 503). Neither silently substitutes a tiny rate
nor returns partial recommendations. Keep existing published prices until resolved.
The two endpoints do not share one error body
Base Price validation errors can be an errors array of strings; other base-price
failures use code and message. Calendar Prices application errors contain
code, message, details, and request_id inside error. The details array
can be empty; it is separate from optional explanation-line details. Gateway
errors may have their own format. First inspect HTTP status, then parse the actual
body defensively.
For a Calendar Prices 422, iterate error.details to show actionable field errors. Do not build a client that assumes every failure has that shape. Capture the X-Request-ID response header when present; never log the API key.
Prevent silent request mistakes
Use exact field names: unknown fields are ignored. For example, an invented rule key can leave a valid request without the adjustment you expected. Validate outgoing configuration against the published schema and inspect returned explanation codes in integration tests.
Omit unused Calendar Prices fields instead of setting them to null; the output start_date and end_date and the two price-limit bounds accept null, which selects their defaults. Use correct JSON types, complete custom settings, and non-overlapping date ranges.