Errors & limits

Errors are JSON with a stable code (branch on this) and a human-readable title (log this). Validation errors may add field details under errors.

Error codes

HTTP	code	Where	Meaning
400	VALIDATION	any	Malformed parameters or body; title says what to fix
401	UNAUTHORIZED	any	Missing/malformed Authorization header, unknown, revoked or expired key, or inactive account
403	FEATURE_DISABLED	any	The agency’s plan does not include API access
403	SCOPE_MISSING	any	Key lacks the required scope (named in the response)
404	NOT_FOUND	any	Unknown unit slug, booking, guest or route
409	BOOKING_CONFLICT	create booking	The nights were taken meanwhile; carries conflict
409	TURNOVER_BLOCK_CONFLICT	create booking	Cleaning block from the previous stay; carries conflict
409	EXPECTED_EXTENSION_CONFLICT	create booking	A current guest is expected to extend into these dates; carries conflicts
422	MIN_STAY	quote, create booking	Stay below the effective minimum; carries minStay
429	RATE_LIMITED	any	Per-minute budget exhausted; honour Retry-After (seconds)
429	QUOTA_EXCEEDED	any	Monthly quota used up; carries quota, used and resetsAt
500	INTERNAL	any	Our bug — safe to retry with backoff; tell us if it persists

Budgets

Two independent ceilings, and they fail differently on purpose: a burst is a pacing problem you fix in seconds, a spent month is a conversation.

	Limit	Counted per	On exhaustion
Per minute	60 requests	API key, shared REST + MCP	429 RATE_LIMITED, retry after seconds
Per month	50,000 requests	agency, all keys together	429 QUOTA_EXCEEDED until the 1st (UTC)

Every answer announces the per-minute budget, so you can pace before you are refused:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 41
X-RateLimit-Reset: 1786784362      # unix seconds

The monthly position is on GET /partner/v1/me and in the agency portal. Keys have their own per-minute budget each, so splitting an integration across two keys buys throughput — but the monthly quota is shared and cannot be split.

{
  "code": "QUOTA_EXCEEDED",
  "title": "The monthly API quota of 50,000 requests is used up.",
  "quota": 50000, "used": 50000, "resetsAt": "2026-09-01T00:00:00.000Z"
}

On 429, back off for the Retry-After seconds and reduce request frequency — batch calendar reads (one call covers a year) instead of fetching month by month. Sustained higher volumes are a support conversation, not a workaround.

MCP errors

The MCP endpoint follows JSON-RPC semantics: protocol problems come back as JSON-RPC errors (-32700 parse, -32600 invalid request, -32601 unknown method, -32602 bad tool/scope, -32603 internal), while tool-level problems (unknown slug, minimum stay, bad dates) come back as successful tools/call results with isError: true and a readable message — that text is meant for the model to read and self-correct.