Dumpster Controls · agent page

This is the agent-optimized version of https://dumpstercontrols.io/help/booking-api/lesson-11-errors-limits-idempotency-and-security: the same content as the human page, without scripts, styles, animations or navigation. People should open the full page.

Canonical page
https://dumpstercontrols.io/help/booking-api/lesson-11-errors-limits-idempotency-and-security
Last updated
2026-10-05
Tokens
1,034 tokens (cl100k_base), within the 2,500-token budget for a help page
Size
8.7 KB for this page, against 30 KB for the human page (71% smaller)
Markdown
https://dumpstercontrols.io/help/booking-api/lesson-11-errors-limits-idempotency-and-security.md, or send Accept: text/markdown to the canonical URL
Cite as
Lesson 11: errors, limits, idempotency and the security model. Dumpster Controls. https://dumpstercontrols.io/help/booking-api/lesson-11-errors-limits-idempotency-and-security (accessed 2026-11-20).
More for agents
Facts sheet · llms.txt · llms-full.txt · All agent pages · Product manual

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
  1. ## 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.
  2. ## 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.
  3. ## 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.
  4. ## 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.
  5. ## 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.
  6. ## 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.