Rate Limits & Errors

Rate limits

The Catalog API follows JOOR's standard rate limiting, documented in full here:

Errors

Errors arrive in the envelope's errors array. Each entry has a machine readable status, a human readable message, and optional details.

{
  "data": [],
  "errors": [
    {
      "status": "NOT_FOUND",
      "message": "Collection not found",
      "details": { "collection_id": "1146216" }
    }
  ]
}

HTTP status codes

Code	Meaning	What to do
`200`	Success
`201`	Created. Returned by subscription create	Store the `secret_key` now
`204`	No content. Returned by unsubscribe	Nothing
`400`	Your request was malformed	Fix it. Do not retry unchanged
`401`	Missing, invalid or expired token	Refresh the token, then retry
`403`	The account is not yours to act for, or is not a retailer account	Check `account`. Do not retry
`404`	The resource does not exist, or is not visible to this account	Treat as "not yours". Do not retry, with one exception — see Bulk Export (Seeding) for a `404` that means "re request this page"
`405`	Method not allowed on this route	Fix the verb
`409`	Conflict. A live subscription already uses this callback	Reuse the existing subscription
`429`	Rate limited	Wait `X-Throttling-Resets-In` seconds
`5xx`	Something failed on our side	Retry with exponential backoff

Retry or not. 401, 429, 5xx, and the one 404 case noted above are worth retrying. Every other status means fix your request or your data, not retry it as is.

Error statuses you will actually see

`status`	Typical cause
`MISSING_REQUIRED_HTTP_QUERY_PARAMETERS`	`account` was not sent
`VALIDATION_ERROR`	`limit` out of range, malformed `cursor`, `callback_url` not HTTPS, unknown key in a request body, an empty `events` array
`INVALID_CHOICE`	`detail` was not `summary` or `full`; `status` filter outside the allowed set
`FORBIDDEN`	Wrong account type, or a subscription that belongs to another account
`NOT_FOUND`	Unknown or invisible collection, product or subscription, or a product that dropped out of a bulk export page mid seed
`TOO_MANY_REQUESTS`	Out of credits

A 404 is deliberate, not a leak. A collection you cannot reach returns 404 rather than an empty page, because an empty page would read as "this collection has no products". The same applies to products and subscriptions.

Unknown keys in a request body are rejected. Subscription create and update reject any field they do not recognise with a 400, rather than ignoring it. A typo in callback_url fails loudly instead of silently creating something you did not intend.