Guide
Errors, retries and rate limits
Recover from errors without duplicating orders, losing an approval or guessing a financial outcome.
Read structured errors
REST errors use an error envelope containing a stable code, a human-readable message and optional details. MCP tool failures set isError and return structured error information.
Validation can reject unknown fields. Do not assume an API silently honored an unsupported request parameter.
{
"error": {
"code": "VALIDATION_ERROR",
"message": "request failed validation",
"details": []
}
}Retry by operation
| Situation | Recovery |
|---|---|
| Transient read failure | Retry with bounded backoff and honor applicable Retry-After metadata. |
| 429 rate limit | Wait for the indicated reset or Retry-After value; do not immediately loop. |
| Mutation with an idempotency key | Retain the original key and exact request. A changed payload is not the same operation. |
| Mutation without a documented retry contract | Read current resource state before deciding what to do. Generic POST retries are not guaranteed safe. |
| Approval or revision conflict | Reload the current state and prepare a new review when the approved bytes changed. |
| Ambiguous provider write | Stop automatic execution and request human reconciliation. Elapsed time does not determine the outcome. |
REST rate-limit visibility
The default API limits are 300 requests per minute per IP, 30 per minute on LLM-backed routes and 3,000 per minute for GET pixel and vanity-link tracking. The POST tracking endpoint uses the global limit. Deployment configuration can change these values; read response headers as the current authority.
Responses expose x-ratelimit-limit, x-ratelimit-remaining and x-ratelimit-reset. Exhausted windows also expose retry-after. These controls are local to an API process; deployment-wide quotas require an appropriately coordinated store or edge policy.
Browser clients can only read cross-origin headers exposed by CORS. The MCP REST client currently does not forward these downstream headers into tool results; do not assume a tool response contains the full HTTP rate-limit contract.
MCP transport limits
The MCP boundary limits request size, read deadlines, authentication deadlines and concurrent requests. The default maximum body is 32 MiB, allowing a 20 MiB decoded creative upload.
Concurrency saturation returns HTTP 503 with Retry-After: 1. That is separate from a REST 429. Streamable HTTP response framing does not provide a campaign event subscription.