After every API response, inspect the JSON body for an 'error' object; do not rely solely on HTTP status codes, as throttle errors are returned in the JSON body.
Map error codes to their scope: code 17 is user-level throttling, code 613 is ad-account-level throttling, and codes 80000–80014 are Business Use Case (BUC) rate limits tied to a specific ad account and endpoint category.
Read the 'x-business-use-case-usage' or 'x-app-usage' response header (where present) to monitor current usage percentage before hitting the limit.
On receiving a BUC error (80000–80014) or code 613, pause all requests for the same ad account and implement exponential backoff: start at 60 seconds and double up to a maximum of 15 minutes.
Log the error subcode alongside the main code for debugging — subcode 1487742 on code 613 indicates mutation rate exceeded for the ad account.
Re-queue failed requests in a durable store (e.g., a job queue) so they are retried after the backoff window; avoid in-memory retry loops that lose work on process restart.
Known gotchas
BUC rate limit errors (80000–80014) are returned in the JSON body, not as HTTP 429 or 400; code 32 applies to the Pages API and does NOT indicate Marketing API throttling.
Each Business Use Case has its own quota bucket per ad account; Ads Management and Insights are separate BUCs, so an Insights throttle does not block mutation calls and vice versa.
The Marketing API development tier has a much lower quota ceiling than the Standard tier; promote your app to Standard before production load testing to avoid misleading throttle results.
Give your agent this knowledge — and 200+ more routes
One MCP install gives any agent live access to the full route map, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp