Limits, retries & errors
Make retries predictable across REST and MCP without repeating side effects.
Limits
| Limit | Value |
|---|---|
| Admitted operations per business | 120 per rolling minute |
| Writes within that total | 20 per rolling minute |
| Request body | 512 KiB |
| Completed write replay window | At least 90 days |
REST and MCP share the limits. These are operational limits, not an additional billing schedule. REST rate-limit responses include Retry-After: 60.
Idempotency
Every write needs a key: Idempotency-Key in REST or idempotency_key in MCP. It must contain 8–80 letters, digits, underscores, or hyphens.
The business, operation, key, and normalized arguments identify one intended action. An identical retry replays the saved response, even across REST and MCP or different credentials for the same business. Replayed REST responses include Idempotency-Replayed: true.
Different arguments with the same key return idempotency_conflict. An action still pending returns operation_in_progress with a receipt ID. Inspect the site or preparation job before deciding on another action; a timeout can happen after an external side effect.
Business errors are also saved for replay. After fixing a failed prerequisite, use a new key for the newly authorized attempt. Do not use a new key merely to retry an uncertain network outcome.
Error handling
| HTTP status | Meaning | Next step |
|---|---|---|
400 | Invalid arguments or missing retry key | Correct the request |
401 | Missing, expired, invalid, or revoked credential | Reconnect or replace the key |
402 | No money for ads (wallet_empty) | Add money for ads (fund_ads) |
403 | Missing scope, business outside the connection, or disallowed browser origin | Check the connection |
404 | Resource not found within the business (business_not_found, no_business: call setup_business) | Check the ID |
409 | State, license, funding, or retry conflict; business_required lists the businesses to choose from | Read the error code and resolve the blocker |
413 | Body too large | Reduce the payload |
429 | Business quota reached | Wait before retrying |
5xx | Internal or provider failure | Inspect state before retrying a write |
MCP tool failures use isError: true with a structured error code. Authentication and protocol errors can occur before the tool runs.
Usage and tracing
REST responses include X-Request-Id; MCP clients receive the receipt in _meta["benjiads/requestId"] and replay information in _meta["benjiads/replayed"]. These diagnostics are kept outside model-visible business data. Keep the receipt when investigating a failure.
get_usage counts admitted operations in the past 30 days, grouped by operation. It includes business failures; requests rejected before admission and replayed receipts do not create a new operation.