Limits and guardrails

The platform is designed so that the safe path is the default path. This page is the honest fine print.

Published limits

240 requests per minute per credential. Exceeding it returns a 429 with a Retry-After header.
SQL results: up to 50,000 rows or 10 MB per response, 120 second query ceiling (60 by default). Paginate or chunk by date beyond that.
Access tokens are short-lived and refresh through the standard token endpoint. Service-credential tokens last 12 hours, so an unattended job that mints one at startup does not need to refresh mid-run. Partner API sessions run the same 12-hour ceiling, matching service credentials. Revoking a credential still stops any new token from being issued; an outstanding token simply runs out within that same ceiling. Amazon-side throttling surfaces as its own error kind so you can back off correctly.

These are generous for interactive use; if you hit them in an automation, batch your requests.

Scoped credentials

Every credential carries explicit permission scopes: account, retail, advertising, brand analytics, context, timeline and MixShift Intelligence reads are separate grants, and the three write permissions (timeline, advertising, listings) are opt-in at mint time. Raw SQL against the warehouse is its own scope, sql:query, separate from the domain reads above; it is bundled by default when a credential is minted with no explicit scope list, but a credential minted with an explicit list needs to request it by name. Every call re-checks its scope, so a read-only credential cannot write no matter what the calling code (or the AI model behind it) asks for. Credentials can be rotated or revoked at any time.

Your data only

A credential resolves server-side to your own tenant database and your own authorized Amazon accounts. The isolation is structural, not a filter: there is no parameter that reaches anyone else's data.

Writes preview first

Advertising and listing writes validate, snapshot, and preview before anything is applied, and commits are audit-logged with the pre-write state. Listing commits replay exactly what was previewed and fail closed if anything drifted. See Work with live Amazon operations.

Predictable errors

Failures return a consistent envelope with a stable machine-readable kind (insufficient scope, throttled, merchant not found, and so on) plus a human-friendly message. Branch on the kind; show the message.

One part of that contract is worth building around deliberately: a failed write does not always mean nothing happened. A few failure kinds are ambiguous by nature, because none of them proves the change was rejected before it was applied: a server error returned from Amazon, a throttle (which can arrive after acceptance), and no response at all. On those, verify the current state before you act, and never blindly re-send the change, or you can apply it twice. Every other kind is a definite rejection, and there it is safe to assume nothing was applied. The operation-level rules are on mcp.mixshift.io/developers.