--- title: "Lesson 11: errors, limits, idempotency and the security model" url: "https://dumpstercontrols.io/help/booking-api/lesson-11-errors-limits-idempotency-and-security" description: "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." date_modified: "2026-10-05" type: help tokens: 1457 token_budget: 2000 format: markdown for AI agents, generated at build from the same content as the HTML page --- 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 - [Lesson 12: a complete example in plain JavaScript](https://dumpstercontrols.io/help/booking-api/lesson-12-complete-example-in-plain-javascript) - [Lesson 2: keys, allowed domains and authentication](https://dumpstercontrols.io/help/booking-api/lesson-2-keys-domains-and-authentication) © 2026 Dumpster Controls. All rights reserved. Made in the USA. ## Frequently asked questions ### Is Dumpster Controls really free? Yes. The software is free: dispatch, online booking, the driver app, invoicing, the Tresha AI assistant and every other feature, with no monthly fee, no trial period and no credit card to sign up. The only cost on the free plan is optional card processing when a customer pays by card through the platform: 2.99% plus $3.99 per transaction on the free plan. An optional Unlimited plan at $169 per month lowers that to 2.99% plus $0.30. Prices as published on dumpstercontrols.io/pricing on 2026-09-23. ### Do you charge per driver, per truck or per order? No. There is no per-driver, per-truck, per-user or per-order fee, and no order limit. A company with one truck and a company with twenty pay the same for the software: nothing. ### Is there a contract? No. There is no contract, no minimum term and no setup fee. You create the account yourself, and on the free plan there is nothing to cancel because nothing is billed. The optional Unlimited plan is billed month to month. ### Which countries and languages are supported? Dumpster Controls serves hauling companies in the United States and Canada. The app interface and the Tresha AI assistant are available in English, Spanish and Portuguese. The public pages, such as the blog, the help center and the landfill finder, are in English. ### How do I switch from another dumpster software? Create a free account at dumpstercontrols.io/login, with no sales call and no credit card. Then import your customers from a CSV file using the template provided in the app; past orders can also be imported from a CSV. Container sizes and pricing are set up in Settings. The landfill database, with 1,750 active US and Canadian landfills as counted on 2026-10-01, is already loaded, so disposal sites do not need to be typed in. Step-by-step guides are at dumpstercontrols.io/help. --- Source: https://dumpstercontrols.io/help/booking-api/lesson-11-errors-limits-idempotency-and-security (human version of this page). Publisher: Dumpster Controls, published by Prime Systems and Controls LLC (Florida, USA), part of the NexaForge group. Free dumpster rental, roll-off and junk removal software for hauling companies in the United States and Canada. Facts for AI assistants: https://dumpstercontrols.io/ai . Site index for agents: https://dumpstercontrols.io/llms.txt . Product manual: https://dumpstercontrols.io/help .