Skip to content
PLUNKDOCS
Create API key

Errors and rate limits

Status codes

Section titled “Status codes”
Status Meaning Body
400 Invalid request: a required field or parameter is missing or unsupported. The body names the field and what’s accepted. An unknown range token is bad_range. { "error": "…", "note": "…" }
401 Missing or invalid key, a publishable key from an unregistered origin, or a secret key from a browser. Message text, with WWW-Authenticate: ApiKey
403 The key is valid but the scope isn’t permitted: the family isn’t enabled for your account, isn’t available to the key’s class, or wasn’t granted to the key. A publishable key on a secret-only write gets secret_key_required. { "error": "scope_not_permitted", "scope": "…" }
404 The resource doesn’t exist. Each endpoint returns a named error, such as product_not_found, dealer_not_found or contact_not_found. { "error": "…", … }
422 A write was understood but nothing in it could be applied. For example, no SKU in an inventory push matches your catalog, or no row in an order-status report was accepted. { "error": "…", … }
429 The key has used its daily or monthly quota. { "error": "quota_exceeded", "message": "…" }
503 An ingest write couldn’t be recorded (ingest_unavailable) or the customer record was busy (ingest_busy). Nothing was saved. Retry with backoff. { "accepted": false, "error": "…" }

Every response is scoped to your account by the key. There is no cross-account surface.

Named errors by family

Section titled “Named errors by family”
Code Status Where
bad_range 400 Any {range} endpoint, for an unknown token
bad_band 400 /dealers/lapse-risk with a band other than healthy, watch, at_risk or lapsing
secret_key_required 403 Sale, order status and reorder requests sent with a publishable key
not_tracked 404 Availability and restock before your account has an inventory snapshot; order status and order requests when your account doesn’t run the order desk
product_not_tracked 404 Availability or restock for a product the inventory feed never lists (for example, made-to-order goods)
not_applicable 404 /dealers/lapse-risk when no account has enough orders to score
similarity_forecast_not_available 404 Similarity forecasts before any have been produced for your account
invalid_status_report 422 /ingest/order-status when no order in the call was accepted
no_matching_skus 422 /ingest/inventory when no SKU matches your catalog
out_of_credits 402 Image calls when your credit balance can’t cover the call
daily_cap 429 Image calls when your account’s daily image limit is reached

Image calls also return 409 when a version needs approval first or is locked by a high-resolution run. See images.

Quotas

Section titled “Quotas”
  • Each key allows 1,000 requests a day and 20,000 a month by default.
  • Every authenticated request counts.
  • The daily count resets at 00:00 UTC. The monthly count resets on the 1st.
  • Past either limit, the API answers 429 quota_exceeded until it resets.

Cache what you can. For higher limits, contact support.

Retrying

Section titled “Retrying”
  • Retry 503 and 429 with exponential backoff. Don’t retry 400, 401, 403, 404 or 422 without changing the request.
  • Ingest writes are safe to retry: posting the same orderId to /ingest/sale replaces that order’s lines.
Section titled “Related”
Was this helpful?

Still stuck? Contact support and include the job or page you were on.