Errors & retries

Understand failures and retry safely without creating duplicate carts.

Errors and retries

Field / limit	Description
image_unreachable	The image host could not be reached, the response was incomplete, or the final response was not HTTP 200.
image_url_unsafe	The URL or redirect is not public IPv4 HTTPS; private/local destinations are blocked.
image_redirect_limit	More than three redirects.
image_timeout	The 15-second total download deadline was exceeded, including DNS, TLS, redirects and body reads.
image_too_large	Source or prepared print image exceeds 20 MiB (20,971,520 bytes).
image_invalid	Not a fully decodable, single-frame PNG/JPEG.
image_pixels_exceeded	Source or image including automatic bleed exceeds 40,000,000 pixels (width × height).
image_hash_mismatch	An optional supplied SHA-256 does not match the downloaded bytes.
content_blocked	This artwork cannot be accepted.
validation_unavailable	Validation/storage could not complete. Create a new cart or contact support.

Malformed requests fail immediately with this envelope; item_index is omitted when the error does not refer to an item:

HTTP request error

{
  "error": {
    "code": "invalid_request",
    "message": "quantity must be a positive integer",
    "item_index": 0
  }
}

Field / limit	Description
400 invalid_request	Correct missing/invalid fields or headers. Remove certification if an older integration still sends it.
401 invalid_api_key	Missing, invalid, revoked or unavailable key. Check the environment and account access.
403 terms_required / content_blocked	A person must accept current terms in the dashboard, or submitted artwork is blocked. Do not bypass a block.
404 not_found	Cart/order is not found for this partner and key mode. An unpaid cart has no manufacturing order yet.
409 idempotency_conflict	The key was already used with different instructions. Use a new Idempotency-Key for the changed request.
413 invalid_request	Request JSON exceeds 512,000 bytes. Send URLs, not image bytes or base64.
429 rate_limited	Wait Retry-After: 60 seconds, then retry. Cart polling is exempt.
500 server_error	Retry with backoff. Preserve the original body and Idempotency-Key for a POST.
503 live_not_enabled / checkout_unavailable / configuration_error	Deployment setup is incomplete or invalid. Contact the platform operator; retry after it is resolved.

An identical POST retry returns the original cart: 202 while validating, otherwise 200. Reusing an idempotency key cannot reopen a failed or expired cart. After an ambiguous network failure, retry with the same key to avoid a duplicate cart.

TCGPlaytest · Cardify LLC Partner terms Support