Developer Docs

Errors And Rate Limits

REST and MCP error posture, retry rules, and rate-limit behavior.

HTTP Status Codes

Status	Meaning	Retry posture
`200`	Success.	No retry needed.
`201`	Created.	No retry needed.
`400`	Malformed JSON, invalid query/body, missing `X-Version`, or schema validation failure.	Fix the request.
`401`	Missing or invalid bearer token.	Refresh credentials.
`403`	Valid key but insufficient route, field, client, or project permission.	Use a narrower workflow or request scope change.
`404`	Resource is missing or invisible to this key.	Verify ID and scope.
`409`	Version conflict, or `archived_record` for a write under an archived client or project.	Re-fetch version conflicts. Do not retry `archived_record`; archived records are read-only.
`429`	Rate limit or backoff.	Respect `Retry-After`.
`500`	Server failure.	Retry only if idempotent; include `request_id` when reporting.

Rate Limits

The shared Redis-backed limiter uses a 60-second rolling window and role-based budgets:

Role	Requests / 60 seconds
`admin`	200
`pm`	100
`studio`	60
`viewer`	30
`client`	30

Repeated violations trigger exponential backoff. 429 responses include Retry-After when the route uses the shared limiter.

Idempotency

Use stable idempotency keys where the route supports them, especially for Shopify staged actions. For write routes without idempotency keys, avoid blind automatic retries after network errors unless the route can be safely de-duplicated by resource ID.

Conflict Recovery

For 409 or stale-version errors:

Re-fetch the resource.
Compare the latest version and fields.
Reapply only the intended change.
Retry with the new X-Version.

An archived write uses the same error envelope with error: "archived_record" and message: "Archived records are read-only". It does not change the resource version or audit state. Archived client and project records remain available to authorized readers, but their child records cannot be changed.