Booking API course · updated 2026-10-05
Lesson 11: errors, limits, idempotency and the security model
A reference you will come back to: the error envelope and every code, the limits, what is idempotent, and what the server guarantees no matter what your page sends.
Before you start
- Any lesson
- ## The error envelope
```
{ "error": { "code": "invalid_body", "message": "rental_days must be an integer between 1 and 365.", "field": "rental_days" } }
```
code is stable and meant for your logic; message is meant for the customer and may change wording; field names the offending input when there is one. - ## Codes by status
400 invalid_body, invalid_parameter, intent_rejected, photo_rejected. 401 unauthorized, origin_required. 403 origin_not_allowed, secret_in_browser, company_inactive. 404 not_found. 405 method_not_allowed. 409 booking_offline, payments_not_ready, date_past, date_closed, out_of_service_area, account_customer, already_authorized, payment_intent_mismatch, unconfirmed, processing, photos_not_available, slot_* (junk). 410 photos_expired. 413 photo_too_large. 415 photo_type. 429 rate_limited (Retry-After). 500 internal. 502 upstream. 503 booking_api_off. - ## Limits
120 requests per minute per key and per IP; payment intents are also capped per company and per IP against card testing. No daily window, no per-call fee, on every plan. Availability: at most 120 days per call. Photos: 3 per job within 2 hours, 8 MB each. - ## Idempotency
/intents with the same session_id reuses the open PaymentIntent. /confirm is idempotent per session: a second call returns the same order with already: true. Webhooks are at-least-once; dedupe on order_number plus event. - ## What the server guarantees
Prices, tax and fees are recomputed from the company's account; no client price is ever used. Booking on, Stripe ready, closed days, service area, promo validity and commercial-account emails are enforced before any payment. Every card payment is screened by Stripe Radar; US companies may hold suspicious orders for review. Card data stays inside the Stripe Payment Element. The publishable key only identifies the company; the server key is hashed at rest. Refunds, cancellations and price changes are not reachable through this API. Everything the API returns is what the public booking page already shows. - ## details in the error envelope
Some errors add details next to code, message and field: invalid_body for an unknown material carries details.allowed (slugs); material_not_allowed (409) carries details.material and details.allowed_sizes (id, label, yards, price). Treat details as optional.
What happens next
- If you build a client library, map the codes above to typed errors and treat every other code as a generic failure with the message.
Troubleshooting
I get 503 booking_api_off.
The API is switched off platform-wide for maintenance. The hosted page and the widget keep working; retry later.
Related guides
© 2026 Dumpster Controls. All rights reserved. Made in the USA.