--- title: "Errors, rate limits and plan limits | Dumpster Controls" url: "https://dumpstercontrols.io/help/api/errors-rate-limits-and-plans" description: "The API uses a consistent error envelope, per-key rate limits, and a daily usage window on the free plan." date_modified: "2026-08-22" type: help tokens: 1307 token_budget: 2000 format: markdown for AI agents, generated at build from the same content as the HTML page --- Developer API · updated 2026-08-22 # Errors, rate limits and plan limits The API uses a consistent error envelope, per-key rate limits, and a daily usage window on the free plan. This article documents every error code you can receive and exactly how the limits work, so your integration can handle each case gracefully. 1. ## The error envelope Every error is JSON with the same shape: ``` { "error": { "code": "...", "message": "..." } } ``` Some errors add fields next to it (for example upgrade_url on plan-limit errors). Always branch on error.code, never on the human message, which can change. 2. ## HTTP status codes 200 success (and 200 with existing:true when a lead POST deduplicates), 201 lead created, 400 invalid_body or invalid_parameter, 401 unauthorized (missing, invalid or revoked key), 403 access_disabled (company gate turned off), 404 not_found, 405 method_not_allowed, 429 rate or plan limits, 500 internal (safe to retry with backoff). 3. ## Rate limit: 60 requests per minute per key All plans. Exceeding it returns 429 with code rate_limited and a Retry-After header in seconds. Spread bursts or add a small queue; the counter resets each minute. 4. ## Free plan: the 10-minute daily window On the free plan, your first API call of the day (company local time) opens a 10-minute window. Calls inside the window are served normally; after it closes, read calls return 429 with code daily_window_ended and an upgrade_url, until the next day. The X-DC-Window-Remaining response header tells you the seconds left. Design free-plan integrations as one scheduled sync burst per day. 5. ## Free plan: 200 leads per day ``` POST /v1/leads does NOT consume the 10-minute window (a lead can arrive at any hour). Instead it has its own quota of 200 leads per day on the free plan; beyond it you get 429 lead_quota_exceeded. Paid plans have no window and no lead quota. ``` 6. ## Paid plans: unlimited Companies on a paid plan have unlimited API access: no daily window, no lead quota. The technical 60 requests/minute per key limit still applies to protect the platform. ## Troubleshooting ### I got daily_window_ended but I barely made any calls. The window is time-based, not call-based: it runs for 10 continuous minutes from your FIRST call of the day, whether you call once or a hundred times. Batch your work into that window. ### Do webhooks count against my window? No. Webhooks are pushed by us and never consume your window or rate limit. ## Related guides - [Get started with the Dumpster Controls API](https://dumpstercontrols.io/help/api/get-started-with-the-api) - [Push and read leads (the CRM and funnel endpoint)](https://dumpstercontrols.io/help/api/push-and-read-leads) © 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/api/errors-rate-limits-and-plans (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 .