Skip to content

Rate Limits

Two limits apply, and a request can run into either one:

LimitApplies toAllowance
Route limitEvery API request, including /auth and /me60 requests per minute per client IP
Resource limitEvery endpoint except /auth and /me30 requests per minute per user

In practice the resource limit is the one you’ll meet: a job that only calls resource endpoints runs out at 30 a minute. /auth and /me don’t count against it, which makes them cheap health checks.

The resource limit is per user, so all of a user’s API keys share the same 30 requests: creating more keys doesn’t add capacity. The route limit is per client IP, so integrations and workers that share an IP address share those 60 requests.

Resource endpoints report the 30-per-minute window:

X-RateLimit-Limit: 30
X-RateLimit-Remaining: 24
X-RateLimit-Reset: 1791201660
HeaderMeaning
X-RateLimit-LimitMaximum requests allowed in the window
X-RateLimit-RemainingRequests left in the window
X-RateLimit-ResetUnix timestamp (UTC, in seconds) when another request is available

/auth and /me report the route limit instead: X-RateLimit-Limit: 60 and the requests left in that bucket.

So don’t carry a count from one endpoint to another. X-RateLimit-Remaining from /me describes the 60-request bucket, not the 30 your resource calls draw on.

Stop sending, and wait:

  1. If Retry-After is present, wait that many seconds.
  2. Otherwise wait until the time in X-RateLimit-Reset.

The body depends on which limit fired. The resource limit returns:

{
"message": "Too many requests. Please try again later.",
"errors": {
"rate_limit": "Too many requests. Please try again later."
}
}

The route limit returns only a message:

{
"message": "Too Many Attempts."
}

Neither has a status field. See Errors for how these fit with the other error shapes.

  • Queue your work rather than firing many requests concurrently.
  • Cache stable IDs. Brand and collection IDs don’t change during a job. Resolve them once.
  • Page efficiently. per_page goes up to 100, so one page often beats four.
  • Use the narrowest list. Post lists filter on the server: ?view=SCHEDULED on one brand-wide call beats paging through every collection.
  • Add jitter when several workers run as the same user or from the same IP, or they’ll all retry in lockstep and re-trigger the limit.
  • Retry reads after the server’s reset time.
  • Don’t blindly retry writes after a timeout or a 5xx. Without a documented idempotency key, the request may have already succeeded. See Errors.

MCP tool calls and CLI commands go through the same public API, so the same limits apply to them. This matters more than it sounds: one conversational request like “show me everything in my account” can chain a brand list, then a collection, channel, media, and post list per brand, and spend a dozen requests before it answers.