Errors

Error shape, codes, rate limits, and how to handle retries safely with idempotency keys.

Errors return a non-2xx status with a JSON body. error is always present. Where a refusal has a stable, machine-readable name it is in error_code; branch on that, not on the wording of error. A few older refusals put their code in error itself (unauthorized, billing_required, free_tier_exhausted, rate_limited, insufficient_scope).

// 400 — missing fields (venue search)
{ "error": "missing required fields", "missing": ["vertical", "datetime"] }
 
// 400 — body is not valid JSON, or a field has the wrong type
{ "error": "invalid request body", "field": "party_size", "detail": "party_size must be a whole number, got string" }
 
// 400 — the guest is a placeholder (POST /v1/bookings)
{ "error": "the customer must be the real guest: ...", "error_code": "placeholder_customer" }
 
// 401 — bad or missing key
{ "error": "unauthorized" }
 
// 402 — live key without billing set up
{ "error": "billing_required", "message": "Live API keys require billing..." }
 
// 402 — test key free allowance exhausted
{ "error": "free_tier_exhausted", "limit": 3, "message": "Test API keys are limited to 3 free calls..." }
 
// 403 — the key lacks the scope this endpoint needs
{ "error": "insufficient_scope", "required_scope": "bookings:create" }
 
// 429 — rate limit exceeded (also sent as the Retry-After header)
{ "error": "rate_limited", "message": "rate limit exceeded", "limit": 25, "retry_after_seconds": 180 }
 
// 400 — POST /v1/bookings with a venue_id that has no resolvable provider
{ "error": "provider required: set the 'provider' field or use a venue_id with a known provider mapping" }

The test-key allowance is counted in confirmed test bookings, not calls: searches and unconfirmed attempts never use it up. Once it is used up, search, availability and booking calls on test keys all return 402 free_tier_exhausted.

AgentCard payment

Codes from AgentCard bookings (payment_collection: "agentcard_external"). HTTP codes come back on the call; the rest appear as the failed booking's error_code.

Other codes

Session codes (live_key_required, invalid_code, reconnect_required and others) are listed on Sessions. A booking whose provider failed is not an HTTP error: it comes back with status: "failed" and its own error_code; see Booking lifecycle.

Rate limits

Limits are per organization, shared by all its API keys, over a fixed 5-minute window. Every metered response carries RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset (seconds until the window resets). Over the limit you get 429 rate_limited with a Retry-After header.

Retrying safely

Send an Idempotency-Key header on POST /v1/bookings. Sending the same key again returns the booking it first created and starts nothing new; the key never expires and the body is not compared. Details are on Booking lifecycle. A 5xx or a timeout on create may still have made a booking: retry with the same key rather than a new one.