Limits and Errors

In short

• Limits are per account and per endpoint over a rolling hour, shared by every key on the account: 2,000 reads, 1,000 product creates, 500 of the other writes, and 1,000 new orders per 24 hours. A call that fails with 400 still counts.
• Over a limit you get 429 { "error": "Rate limit exceeded" } with no Retry-After header. Wait at least a minute, then back off further.
• Every error is JSON with an error message, sometimes an errors array naming the items that failed, and on 402 a credits object.
• Reads are always safe to retry. Writes are safe when they carry an idempotent key: external_order_number on orders, the SKU on products and bundles. A 409 or an “already exists” 400 on a retry means the first attempt worked.
• The one call to never retry blind is POST /api-bulk-list without explicit SKUs, because the generated SKUs get a number added and you create duplicate drafts. Check GET /api-bulk-list first.

Rate limits

• Each limit is a rolling window per endpoint, so hitting the product limit doesn’t stop you reading orders.
• Limits are per account, not per key. Extra keys don’t raise them.
• The limit is counted before the body is checked, so invalid requests that come back 400 use it up like any other. Validate on your side first.
• Budget reads for what matters: for many orders, use the list form of GET /api-get-order (25 per page) rather than one read per order, and poll every 30 to 60 minutes, which is as fast as orders move.

Error format

{ "error": "SKU must be 50 characters or less." }

{ "error": "1 of 2 images failed validation. Nothing was created.",
  "errors": [ { "index": 1, "image_url": "https://example.com/oak-leaf.png", "error": "Artwork is 2:3 (1024x1536px) but template \"Botanical\" is A-series. Use a 2:3 template or resize the file." } ] }

{ "error": "Not enough credits: this request needs 12 and you have 4. Top up or send fewer images.",
  "credits": { "cost": 12, "available": 4 } }

Successful responses carry "success": true. Keys look like psk_live_ plus 32 characters, and they don’t expire; a revoked key returns 401 immediately.

Status codes

The 400s you will meet most

• Orders: Missing customer information: zip. All of these are required: name, address1, city, zip, country · Country must be a 2-letter ISO code (e.g. "GB", "US", "AU"). Received: "UK" · State/province is required for United States. Please provide a "state" field. · Shipping option "priority" is only available for United Kingdom. Use "standard" for other countries. · Product[0]: Missing required field: paper_type. Accepted values: Matte, Satin, Gloss · Product[1]: Frame orders require a "variant" field. Accepted values: Black, White, Oak · Product[0]: Provide either "sku" (to reference a saved product) or "image.artwork_url" (to provide artwork directly), not both. · An order with external_order_number "SHOP-1001" already exists.
• Products: Missing required field: name · SKU must be 50 characters or less. · Too many variants. Maximum 22 variants per request. · variants[1]: Invalid size "a4". Accepted values: ... (sizes are case-sensitive) · variants[0]: Duplicate size "A4". ... · variants[0]: Invalid image_url: <reason> · the account has reached 25,000 products.
• Pricing: Missing required query parameter: country · Unknown country: XX.
• Bulk List and bundles: a 400 with an errors array, one entry per failing item with its index and reason, and nothing created. Fix the items named and resend the whole request.

Retrying safely

Timeouts

A timeout or a dropped connection on a write means you don’t know whether it happened. Don’t guess: read first. GET /api-get-order?external_order_number=..., GET /api-get-product?sku=..., GET /api-get-bundle?sku=... and the list form of GET /api-bulk-list each tell you in one call, and then you retry only what is missing. Give every order an external number and every product and bundle a SKU you chose, and this is always possible.

A backoff that works

• On 429: wait 60 seconds, then 2, 4 and 8 minutes between further attempts. Since the window is a rolling hour, spreading calls out beats bursting.
• On 500 for a read: retry after a few seconds, up to three times, then stop and report it.
• On 400, 401, 404, 405 and 409: don’t retry the same request. Each one is telling you something to change or something already done.
• On a timeout: read, then retry the write if needed.

Other limits