Errors

Every error has the same shape, with a stable code to branch on. The message is written for people and its wording can change.

402 Payment Required
{
  "error": {
    "code": "insufficient_credit",
    "message": "This needs 1745 cents of credit and 1200 is available.",
    "field": null,
    "docs_url": "https://www.quantum-production.com/docs/errors#insufficient_credit",
    "retryable": false,
    "request_id": "req-7Hq2Lw",
    "details": {
      "required": {
        "amount": 1745,
        "currency": "USD"
      },
      "available": {
        "amount": 1200,
        "currency": "USD"
      }
    }
  }
}
FieldTypeDescription
errorrequiredobject
error.coderequiredErrorCode
error.messagerequiredstring

For people. The wording can change.

error.fieldrequiredstring or null

The request field at fault, as a JSON path such as items[0].page_count.

error.docs_urlrequiredstring (URL)
error.retryablerequiredboolean

Whether the same request might succeed later.

error.request_idrequiredstring
error.detailsobject

Extra facts for some codes, such as required and available on insufficient_credit.

Quote the request_id when you contact support about an error. It finds the request in our logs.

Error codes

invalid_request400

The body isn't valid JSON, a field is missing or out of range, or the Idempotency-Key header is missing. field names the problem as a JSON path, such as items[0].page_count.

Fix: Correct the field named in field and send the request again.

Don't retry unchanged.

unauthorized401

The Authorization header is missing, or the key is malformed, unknown or revoked.

Fix: Send Authorization: Bearer <key> with an active key from the dashboard's API keys page.

Don't retry unchanged.

forbidden403

The key can't do this. Until live ordering opens, live keys get it on estimates, orders and order changes.

Fix: Use a sandbox key (qp_test_…) for now.

Don't retry unchanged.

account_suspended403

A plan payment failed and the account is suspended. Orders already in production still ship.

Fix: Update the card in the dashboard. New orders are accepted again once the payment goes through.

Don't retry unchanged.

sandbox_only403

A live key called a sandbox tool, such as advancing an order by hand.

Fix: Call it with a sandbox key, on a sandbox order.

Don't retry unchanged.

not_found404

There's no such order for this key's account and mode, or no such route. A sandbox key can't see live orders, and a live key can't see sandbox ones.

Fix: Check the order id, and that the key's mode matches the order's.

Don't retry unchanged.

insufficient_credit402

Your balance doesn't cover the order, or the extra shipping after an address change. Nothing is charged. details has required and available.

Fix: Top up your credit in the dashboard, then send the same request again.

Don't retry unchanged.

idempotency_conflict409

This Idempotency-Key was already used for a different request body.

Fix: Use a new key for a new order. Reuse a key only to retry the exact same request.

Don't retry unchanged.

sku_not_found422

You have no SKU with the code in items[].sku.

Fix: Set the SKU up on the dashboard's Products page, or correct the code. GET /products lists yours.

Don't retry unchanged.

sku_not_orderable422

The SKU is switched off, or its product isn't available to order right now.

Fix: Check the SKU's status on the Products page.

Don't retry unchanged.

proof_required422

No longer returned: proofs have been optional since October 2026, and any SKU that isn't off takes normal orders.

Fix: Nothing to do. The code stays listed so integrations that handle it keep working.

Don't retry unchanged.

page_count_out_of_range422

items[].page_count is outside the product's range or not a multiple of its step. details has min, max and multiple_of.

Fix: Send a page count the product takes. The products page lists each one's range.

Don't retry unchanged.

file_unreachable422

A file link can't be downloaded.

Fix: Make sure the link is a public https:// address that stays downloadable until the order ships.

Don't retry unchanged.

shipping_method_unavailable422

The address is outside the US and Canada, or express or overnight was asked for to Canada.

Fix: Ship to a US or Canadian address, and use standard for Canada.

Don't retry unchanged.

order_not_cancellable409

The order is in production, or has already shipped, been cancelled or been rejected.

Fix: Orders can be cancelled while they are received or needs_attention, before production starts. Contact Quantum support about one that's in production.

Don't retry unchanged.

address_not_editable409

The shipping label has printed, or the order has ended.

Fix: Addresses can change until the label prints. After that, contact Quantum support.

Don't retry unchanged.

invalid_status_transition409

A sandbox order was asked to move backwards, to the status it already has, or out of shipped, cancelled or rejected.

Fix: Advance sandbox orders forward only, or to needs_attention, cancelled or rejected.

Don't retry unchanged.

rate_limited429

Too many requests in a short time.

Fix: Wait the number of seconds in the Retry-After header, then retry.

Retry later.

internal_error500

Something went wrong on Quantum's side.

Fix: Retry with backoff. If it keeps happening, contact support with the request_id.

Retry later.

service_unavailable503

A service the request depends on, such as shipping rates, is unavailable for a moment.

Fix: Retry with backoff when retryable is true.

Retry when the response says retryable.

Errors · Quantum Production