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

​
HTTP Status Codes

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

​
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 CodeDescription
not_foundResource was not found
validation_errorA parameter was incorrect or missing. Check details for more information
bad_requestThe request was malformed or invalid
already_existsResource already exists (e.g., duplicate idempotency key)
internal_errorSomething 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 CodeDescription
unauthorizedAuthentication is required for this action
forbiddenYou do not have permission for this action
invalid_tokenYour API token is invalid
token_expiredYour API token has expired

​
Example

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

​
Wallet & Payment Errors

Error CodeDescription
insufficient_fundsInsufficient funds in wallet for the order
payment_failedPayment operation failed
payment_method_requiredNo default payment method configured
invalid_payment_methodThe provided payment method is invalid

​
Example

{
  "code": "insufficient_funds",
  "message": "Your wallet balance is insufficient for this order",
  "details": {
    "required": 4999,
    "available": 1000
  }
}

​
Order Request Errors

Error CodeDescription
invalid_shipping_addressThe shipping address failed validation
url_unreachableThe product URL provided is inaccessible
invalid_variantProduct variant not provided or not found on product page
out_of_stockProduct is not currently available for purchase
shipping_unavailableShipping to this address is not available
non_us_retailerOnly US retailer sites are supported
order_not_cancellableOrder cannot be cancelled due to its current status

​
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 CodeDescription
external_service_errorAn external service call failed

​
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:

​
Product Errors

Error TypeDescription
product_not_foundProduct page doesn’t exist or was removed
product_out_of_stockProduct is out of stock
product_unavailableProduct exists but cannot be purchased
invalid_product_urlURL is malformed or not a valid product page
product_variant_requiredProduct requires a variant selection
product_variant_unavailableSelected variant is not available
product_quantity_unavailableRequested quantity is not available

​
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 TypeDescription
max_price_exceededTotal 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 TypeDescription
add_to_cart_failedCould not add product to cart
cart_emptyCart became empty during checkout
checkout_blockedCheckout blocked (captcha, verification, etc.)
checkout_failedGeneric 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"
  }
}

​
Shipping Errors

Error TypeDescription
shipping_address_invalidAddress validation failed on retailer site
shipping_unavailableCannot ship to the given address
shipping_method_unavailableNo 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 TypeDescription
payment_declinedPayment was declined by retailer
payment_method_invalidPayment method not accepted
payment_failedGeneric 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 TypeDescription
login_failedCould not log into retailer account
session_expiredSession expired during checkout
account_lockedRetailer account is locked or suspended
account_verification_requiredAccount 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 TypeDescription
retailer_unavailableRetailer website is down or inaccessible
retailer_not_supportedRetailer is not supported
retailer_rate_limitedRate limited by retailer

​
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 TypeDescription
quantity_limit_exceededRetailer has purchase quantity limits
order_limit_exceededAccount has reached order limits

​
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"
  }
}