Error Handling - Zinc Docs

The Zinc API uses conventional HTTP response codes to indicate the success or failure of an API request.

HTTP Status Codes

Status Code	Description
`200`	Success - The request was successful
`201`	Created - A new resource was created successfully
`400`	Bad Request - The request was malformed or invalid
`401`	Unauthorized - Invalid or missing authentication
`402`	Payment Required - Payment or wallet issue
`403`	Forbidden - You don’t have permission to access this resource
`404`	Not Found - The requested resource does not exist
`409`	Conflict - Resource already exists
`422`	Unprocessable Entity - Validation error
`429`	Too Many Requests - Rate limit exceeded
`500`	Internal Server Error - Something went wrong on our end
`502`	Bad Gateway - External service error
`503`	Service Unavailable - A dependency is temporarily unavailable

Error Response Format

All error responses follow a consistent structure:

{
  "code": "error_code",
  "message": "Human-readable error message",
  "details": {
    "field": "Additional context about the error"
  }
}

API Error Codes

General Errors

Error Code	Description
`not_found`	Resource was not found
`validation_error`	A parameter was incorrect or missing. Check details for more information
`bad_request`	The request was malformed or invalid
`already_exists`	Resource already exists (e.g., duplicate idempotency key)
`rate_limit_exceeded`	You have exceeded your request rate limit (`429`). Back off and retry
`service_unavailable`	A dependency is temporarily unavailable (`503`). Retry shortly
`internal_error`	Something went wrong with our internal systems

Example

{
  "code": "validation_error",
  "message": "Invalid request parameters",
  "details": {
    "products": "At least one product is required"
  }
}

Authentication Errors

Error Code	Description
`unauthorized`	Authentication is required for this action
`forbidden`	You do not have permission for this action
`invalid_token`	Your API token is invalid
`token_expired`	Your API token has expired

Example

{
  "code": "invalid_token",
  "message": "The provided API token is not valid"
}

Device Authorization Errors

Returned by POST /device/token while an agent polls for approval. These follow RFC 8628, so three of the four are not failures — they report where the flow is, and only access_denied means stop.

Error Code	Status	Description
`authorization_pending`	`400`	Nobody has approved or denied the code yet. Keep polling at `details.interval`
`slow_down`	`400`	You polled faster than `interval`. Back off; the code is still valid
`expired_token`	`400`	The code is unknown, expired, or already redeemed. Start again with `POST /device/code`
`access_denied`	`403`	The account owner declined. Do not retry on your own

authorization_pending and slow_down both carry details.interval, the number of seconds to wait (default 5).

Example

{
  "code": "authorization_pending",
  "message": "Waiting for the account owner to approve",
  "details": {
    "interval": 5,
    "hint": "Poll again in 5s. Do not open another browser or start a new code; the one you showed is still valid."
  }
}

expired_token also covers a code that was already redeemed — a key is handed over exactly once. Retrying a successful redeem returns this, not the key again.

Wallet & Payment Errors

Error Code	Description
`insufficient_funds`	Wallet balance is below what the order requires. An order on Zinc’s accounts needs `max_price` + the API fee; an order on your own retailer account needs the API fee only
`payment_failed`	Payment operation failed
`payment_method_required`	No default payment method configured
`invalid_payment_method`	The provided payment method is invalid

Example

{
  "code": "insufficient_funds",
  "message": "Insufficient wallet balance. Required: $49.99, Available: $10.00",
  "details": {
    "required": 4999,
    "available": 1000
  }
}

required is max_price + the API fee, because an order with no retailer_credentials_id is placed on a Zinc account and the item comes out of your wallet. details.fund_with lists every way forward; when you already have your own retailer account saved for that store it is listed first, as the your_retailer_account rail, and naming it drops the balance required to the API fee alone. See Retailer Accounts and the rails.

The metered data endpoints are the one exception to the envelope above. GET /search and the /products/* endpoints return a bare {"detail": "Insufficient wallet balance for data API call"} with their 402, not an error object — read detail, not error.code, when handling a shortfall on those.

Order Request Errors

Error Code	Description
`invalid_shipping_address`	The shipping address failed validation
`url_unreachable`	The product URL provided is inaccessible
`invalid_variant`	Product variant not provided or not found on product page
`out_of_stock`	Product is not currently available for purchase
`shipping_unavailable`	Shipping to this address is not available
`unsupported_retailer`	The product URL is from a retailer Zinc will not order from
`unsupported_country`	The requested shipping country is not supported
`guest_checkout_not_supported`	The retailer needs a linked account; pass `retailer_credentials_id`
`order_not_cancellable`	Order cannot be cancelled due to its current status
`return_not_allowed`	A return is not allowed for this order

unsupported_retailer, unsupported_country, and guest_checkout_not_supported are all predictable before you submit an order — ask GET /retailers/check with the product URL and destination country first.non_us_retailer is a legacy value that the API no longer returns. Zinc is not US-only; if you branch on it, that branch is dead.

Example

{
  "code": "invalid_shipping_address",
  "message": "The shipping address could not be validated",
  "details": {
    "field": "postal_code",
    "reason": "Postal code does not match city/state"
  }
}

External Service Errors

Error Code	Description
`external_service_error`	An external service call failed (`502`)
`stripe_error`	A Stripe API call failed, e.g. during wallet auto top-up
`stytch_error`	A Stytch API call failed during authentication

Example

{
  "code": "external_service_error",
  "message": "Unable to connect to external service. Please try again."
}

Order Processing Errors

When an order fails during processing, the error_type field in the order response or webhook payload contains one of these codes:

On a best-effort order, some of these codes stop being failures. A code covered by a concern you relaxed is recorded as an entry in fulfillment.concessions and the order goes ahead — the same code, reported as something that was worked around rather than something that stopped the order.

Structured error details

Alongside the flat error and error_type keys (kept for backward compatibility), a failed job result may include an error_details object. This is the structured home for enrichment beyond the category and message — for example, the specific reasons a shipping address was rejected, or which fields failed validation.

Field	Type	Description
`code`	string	Machine-readable error code
`message`	string	Human-readable error message
`url`	string \| null	The item this failure is about, matching an `OrderItem.url` on the order. `null` on order-level failures (address, payment, empty cart) — a missing `url` means the failure isn’t attributable to one item, never “the first item”
`address_validation_reasons`	string[]	Reasons a shipping address was rejected, when applicable
`field_errors`	array	Per-field validation failures (see below)
`line_rejections`	array	Per-item rejections reported by the retailer (see below)

Each entry in field_errors is a FieldError:

Field	Type	Description
`field`	string	The offending field
`code`	string	Machine-readable failure code
`message`	string	Human-readable description
`received`	any	The value that was received
`expected`	string \| null	The expected value or format, when known

Each entry in line_rejections is a LineRejection: one order line the retailer rejected, as the retailer reported it. It’s currently reported for Amazon orders and is empty on order-level failures. Lines the retailer cancelled only because another line was rejected aren’t listed.

Field	Type	Description
`url`	string \| null	The rejected item’s URL, matching an `OrderItem.url`
`product_id`	string \| null	The retailer’s product ID (an ASIN on Amazon)
`requested_quantity`	integer \| null	Units requested on the line
`available_quantity`	integer \| null	Units the retailer will currently sell, when it says. Amazon’s quantity limits are cumulative per account, so this can be `0` even for a 1-unit line
`codes`	string[]	The retailer’s raw rejection codes (e.g. Amazon’s `015-003`)
`messages`	string[]	The retailer’s raw rejection messages

Example

{
  "event": "order.failed",
  "order_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "failed",
  "timestamp": "2026-01-15T14:30:00Z",
  "data": {
    "error_type": "shipping_address_invalid",
    "error": "The shipping address could not be validated",
    "error_details": {
      "code": "shipping_address_invalid",
      "message": "The shipping address could not be validated",
      "address_validation_reasons": [
        "Postal code does not match city/state"
      ],
      "field_errors": [
        {
          "field": "state",
          "code": "invalid_value",
          "message": "state should be a 2-letter code",
          "received": "New York",
          "expected": "NY"
        }
      ]
    }
  }
}

Product Errors

Error Type	Description
`product_not_found`	Product page doesn’t exist or was removed
`product_out_of_stock`	Product is out of stock
`product_unavailable`	Product exists but cannot be purchased — including whole categories Zinc never buys, such as digital goods and gift cards. See Products Zinc cannot buy
`invalid_product_url`	URL is malformed or not a valid product page
`product_variant_required`	Product requires a variant selection
`product_variant_unavailable`	Selected variant is not available
`product_quantity_unavailable`	Requested quantity is not available

An order sent with fulfillment: { "items": "best_effort" } skips the offending item and ships the rest instead of failing on these codes. The item’s status becomes skipped, and the code lands in fulfillment.concessions. An order whose every item was skipped still fails, as cart_empty.

Example

{
  "event": "order.failed",
  "order_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "failed",
  "timestamp": "2026-01-15T14:30:00Z",
  "data": {
    "error_type": "product_out_of_stock",
    "error": "The requested product is currently out of stock"
  }
}

Price Errors

Error Type	Description
`max_price_exceeded`	Total price exceeds the `max_price` limit

Example

{
  "event": "order.failed",
  "order_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "failed",
  "timestamp": "2026-01-15T14:30:00Z",
  "data": {
    "error_type": "max_price_exceeded",
    "error": "Order total of $52.99 exceeds max_price of $50.00"
  }
}

Cart & Checkout Errors

Error Type	Description
`add_to_cart_failed`	Could not add product to cart
`cart_empty`	Cart became empty during checkout — including a best-effort order in which every item was skipped
`checkout_blocked`	Checkout blocked (captcha, verification, etc.)
`checkout_failed`	Generic checkout failure

Example

{
  "event": "order.failed",
  "order_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "failed",
  "timestamp": "2026-01-15T14:30:00Z",
  "data": {
    "error_type": "checkout_blocked",
    "error": "Checkout requires additional verification"
  }
}

Gift Errors

Error Type	Description
`gift_option_unavailable`	Order requested `is_gift`, but the retailer’s checkout offers no free gift option

An order submitted with is_gift: true fails with this error type rather than being placed as a normal order — a gift arriving with prices visible to the recipient is treated as worse than no order. If gifting is an optional add-on in your flow, catch this error type and retry without is_gift to place the order as a standard purchase. See Gift orders. Alternatively, opt out of the failure up front with fulfillment: { "gift": "best_effort" } — a retailer with no gift option then gets a normal order rather than none, and the order reports the substitution in fulfillment.concessions.

gift_message does not fail this way. Where a retailer’s checkout has no gift-message field, the order is still placed without the message.

Example

{
  "event": "order.failed",
  "order_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "failed",
  "timestamp": "2026-01-15T14:30:00Z",
  "data": {
    "error_type": "gift_option_unavailable",
    "error": "This retailer does not offer a free gift option at checkout"
  }
}

Shipping Errors

Error Type	Description
`shipping_address_invalid`	Address validation failed on retailer site
`shipping_unavailable`	Cannot ship to the given address
`shipping_method_unavailable`	No shipping methods available

Example

{
  "event": "order.failed",
  "order_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "failed",
  "timestamp": "2026-01-15T14:30:00Z",
  "data": {
    "error_type": "shipping_unavailable",
    "error": "This item cannot be shipped to the selected address"
  }
}

Payment Errors

Error Type	Description
`payment_declined`	Payment was declined by retailer
`payment_method_invalid`	Payment method not accepted
`payment_failed`	Generic payment failure

Example

{
  "event": "order.failed",
  "order_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "failed",
  "timestamp": "2026-01-15T14:30:00Z",
  "data": {
    "error_type": "payment_declined",
    "error": "The payment method was declined by the retailer"
  }
}

Account Errors

Error Type	Description
`login_failed`	Could not log into retailer account
`session_expired`	Session expired during checkout
`account_locked`	Retailer account is locked or suspended
`account_verification_required`	Account needs verification

Example

{
  "event": "order.failed",
  "order_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "failed",
  "timestamp": "2026-01-15T14:30:00Z",
  "data": {
    "error_type": "login_failed",
    "error": "Unable to authenticate with retailer account"
  }
}

Retailer Errors

Error Type	Description
`retailer_unavailable`	Retailer website is down or inaccessible
`retailer_not_supported`	Retailer is not supported
`retailer_rate_limited`	Rate limited by retailer

Refusals you can predict

Three of these refusals are decided from the store and destination alone, so you do not have to submit an order to discover them. GET /retailers/check returns the same code up front in unsupported_reason:

Error Code	Returned when
`retailer_not_supported`	The store is marked unsupported or retired
`retailer_country_not_supported`	The store declares `ships_to` and your destination is not in it
`invalid_product_url`	The URL has no registrable domain, so there is no store to check

The codes are reused verbatim from the order path, so a refusal from /retailers/check and one from POST /orders for the same URL cannot disagree.

Example

{
  "event": "order.failed",
  "order_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "failed",
  "timestamp": "2026-01-15T14:30:00Z",
  "data": {
    "error_type": "retailer_unavailable",
    "error": "The retailer website is currently unavailable"
  }
}

Quantity Limit Errors

Error Type	Description
`quantity_limit_exceeded`	Retailer has purchase quantity limits
`order_limit_exceeded`	Account has reached order limits

An order sent with fulfillment: { "quantity": "best_effort" } buys the retailer’s cap instead of failing with quantity_limit_exceeded, and reports the requested and fulfilled counts in fulfillment.concessions. order_limit_exceeded is your own account limit and is not relaxable.

Example

{
  "event": "order.failed",
  "order_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "failed",
  "timestamp": "2026-01-15T14:30:00Z",
  "data": {
    "error_type": "quantity_limit_exceeded",
    "error": "Maximum purchase quantity for this item is 3"
  }
}

​HTTP Status Codes

​Error Response Format

​API Error Codes

​General Errors

​Example

​Authentication Errors

​Example

​Device Authorization Errors

​Example

​Wallet & Payment Errors

​Example

​Order Request Errors

​Example

​External Service Errors

​Example

​Order Processing Errors

​Structured error details

​Example

​Product Errors

​Example

​Price Errors

​Example

​Cart & Checkout Errors

​Example

​Gift Errors

​Example

​Shipping Errors

​Example

​Payment Errors

​Example

​Account Errors

​Example

​Retailer Errors

​Refusals you can predict

​Example

​Quantity Limit Errors

​Example

HTTP Status Codes

Error Response Format

API Error Codes

General Errors

Example

Authentication Errors

Example

Device Authorization Errors

Example

Wallet & Payment Errors

Example

Order Request Errors

Example

External Service Errors

Example

Order Processing Errors

Structured error details

Example

Product Errors

Example

Price Errors

Example

Cart & Checkout Errors

Example

Gift Errors

Example

Shipping Errors

Example

Payment Errors

Example

Account Errors

Example

Retailer Errors

Refusals you can predict

Example

Quantity Limit Errors

Example