Errors and rate limits

Errors are returned as JSON with a consistent shape so you can handle them uniformly.

Error envelope

{
  "error": "rate_limited",
  "message": "Too many requests.",
  "retry_after": 30
}

error is a stable machine-readable code; message is human readable. Some errors carry extra fields (for example retry_after on a 429, field-level details on a 422, or a reference correlation code on a 500).

Status codes

Code	Meaning	What to do
`200`	Success	Read the body.
`401`	Not authenticated	Check the bearer token; it may be missing, expired, or revoked.
`403`	Not permitted	The key lacks the required scope, or your shop does not have API access.
`404`	Not found	The resource does not exist for this shop.
`409`	Conflict	The request conflicts with an existing resource. Customer creation returns `duplicate_customer` with `existing_customer_id` when a duplicate is found.
`422`	Validation failed	Fix the request; the body lists what was wrong.
`429`	Rate limited	Back off and retry after `Retry-After`.
`500`	Server error	Something went wrong on our side. The body carries a short `reference` code; retry later, and quote the `reference` to support if the error persists.
`503`	Temporarily unavailable	The API is briefly offline for maintenance. Retry later.

Identifiers are scoped to your shop. A resource that belongs to another shop is reported as 404, never another shop’s data.

Rate limiting

Requests are rate limited per token, per shop, and per IP address. When you exceed any of these limits you receive a 429 carrying:

Retry-After (seconds to wait),
X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset.

Respect Retry-After and use exponential backoff. Spread bulk reads over time rather than bursting.

Good citizenship

Cache responses where you can and poll with filter[updated_since] instead of re-reading everything.
Prefer webhooks for change notifications; reserve polling for reconciliation.
Treat repeated 404s as a bug in your integration, not a way to discover records.

Partner API

Endpoints

Error envelope

Status codes

Rate limiting

Good citizenship

​Error envelope

​Status codes

​Rate limiting

​Good citizenship

Error envelope

Status codes

Rate limiting

Good citizenship