Errors | Cardzone Developers

This page lists every error the API can return, and what to do about each one.

A 4xx HTTP status means a problem on your side, such as a bad API key, a missing field, or a low store wallet balance. A 5xx HTTP status means a problem on Cardzone’s side.

The error shape

Every error response has the same shape:

{
  "error": {
    "code": "validation_failed",
    "message": "Validation failed",
    "details": {
      "product_id": ["is required"],
      "quantity": ["must be greater than 0"]
    }
  }
}

code is a fixed, machine-readable value. Your code MUST make decisions based on it, together with the HTTP status.
message is text for people. It may be translated if you send Accept-Language.
product_status appears on product 404 errors when Cardzone knows why the product can’t be ordered: out_of_stock or unavailable.
details is optional. For validation_failed, it usually maps each field to its problems. But it can also be a single string, such as "product_not_found". Check its type before you read it.
Every response has an X-Request-Id header. Include it when you contact support about a request.

Codes

Status	`code`	Meaning	Retry?
401	`unauthorized`	The API key is missing, unknown, or revoked. Or it is a live API key whose store is inactive or not verified yet. See authentication.	No
403	`forbidden`	The API key doesn’t have the permission for this endpoint.	No
403	`insufficient_store_wallet_balance`	The store of a live API key is below the store wallet minimum. `details.minimum_prepaid_balance` has the amount.	After you recharge
403	`player_lookup_requirements_not_met`	The same store wallet rule, for player lookups.	After you recharge
403	`sandbox_order_cancellation_not_supported`	You called cancel with a sandbox API key.	No
404	`category_not_found`	List products: no category matches the `category_id`.	No
404	`validation_failed` with `details: "product_not_found"`	Create order: the product doesn’t exist, or this store can’t order it now. When Cardzone knows why, `error.product_status` is `out_of_stock` or `unavailable`. See availability.	Later, for `out_of_stock`. Otherwise, refresh the catalog.
404	`product_not_found`	Look up player profile: the product doesn’t exist, or it can’t be fulfilled for this store. `error.product_status` is included when known. Lookups still work for products that are only out of stock or hidden.	Refresh the catalog
404	`validation_failed` with `details: "payment_option_not_found"`	Create order: the product has no price set up that can be bought. This is rare. It is a catalog problem on Cardzone’s side.	Contact support
404	`order_not_found`	No order with that `order_id`, or no API order with that `merchant_order_ref`, in this store.	No
409	`merchant_order_ref_already_used`	An order with this `merchant_order_ref` already exists.	No. Look it up by `merchant_order_ref`.
409	`order_not_cancelable`	See `details.reason_code`.	Maybe later
422	`validation_failed`	See `details` for each field.	Fix the request
422	`delivery_method_not_allowed`	Player lookup: this API key can’t order this product’s delivery type. Create order reports the same case as `validation_failed` with `details.delivery_type`.	No
429	`rate_limited`	Too many player lookups for this store. There is no `Retry-After` header. Wait, then retry, and wait longer each time (back off).	After a pause

Here is a request that fails validation. Look at details:

A validation errorRecorded sandbox response

No key

POST

Request body

Response

Validation messages you’ll see

`details` entry	How to fix it
`"product_id": ["is required"]`	Send `product_id`.
`"quantity": ["must be greater than 0"]`	Send a positive whole number (integer).
`"merchant_order_ref": ["is too long (maximum is 128 characters)"]`	Shorten the `merchant_order_ref`.
`"recipient": ["is missing zone_id"]`	Send every key in the product’s `recipient_fields`.
`"recipient": ["contains unexpected fields: email"]`	For a top-up, send only the keys in `recipient_fields`.
`"recipient": ["must be an object"]`	Send `recipient` as a JSON object.
`"product_id": ["is not a top-up product"]`	Player lookups only work for top-up products.
`"https_required"`, `"host_required"`, `"private_host"`, `"invalid_url"` (as the whole `details`)	Send a `webhook_url` that starts with `https://` and has a public host.
`"recipient": ["topup recipient fields are not accepted for voucher products"]`	Vouchers take only `name`, `email`, and `mobile`.