Errors & troubleshooting

Common API errors and how to resolve them.

Response format

Errors still use the standard envelope:

{
  "success": false,
  "message": "Error description",
  "data": { ... }
}

Always check success. On failure, use message and optional data for details. HTTP status codes indicate the type of error.

Common HTTP status codes

Code	Meaning	What to do
400	Bad request	Check `data.state`: `invalid_quantity`, `out_of_stock`, or terminal failure. When `data.order_id` is present, call `GET /orders/{id}` before treating as final — status may be `pending`. Failed idempotency replay: use a new key for a new purchase.
402	Payment required	Insufficient API wallet balance. Top up your CardPlusPay account before retrying the purchase.
401	Unauthorized	Missing or invalid API key. Ensure the `X-API-Key` header is set and the key is active in the dashboard.
404	Not found	Invalid item_code, order_id, or resource. Confirm the ID exists and belongs to your account.
409	Conflict	`idempotency_conflict` — Different body with the same key, or order still processing. When `data.order_id` is present, call `GET /orders/{id}` and poll until terminal; do not create a duplicate order. If parameters differ, use a new key for a new purchase.
422	Validation error	Invalid format or field validation: `missing_fields`, `invalid_fields`, `validation_error`. Check `data.field` when present.
501	Not implemented	`not_supported` — SKU not available for API purchase yet.
429	Too many requests	Rate limit exceeded. Slow down requests or implement backoff.
500	Server error	Unexpected server-side error. Retry later; if it persists, contact support.

Frequent issues

401 after adding the key — Confirm the header name is exactly X-API-Key (case-sensitive). No extra spaces or quotes around the key. Ensure the key is not revoked or inactive.
404 on catalog or order — For catalog, ensure item_id / item_code matches a product from GET /catalog. For orders, use the order_id returned from POST /orders.
400 on create order — Read data.state and message. If order_id is in the body, GET /orders/{id} before refunding — order may still be pending.
Empty codes but HTTP 200 — Check data.status. If pending, poll GET /orders/{id} — do not treat as failure. For direct_top_up, use delivery.status instead of codes.
422 missing_fields / invalid_fields — Direct top-up: fix fields per catalog required_fields. See validate fields.
402 on create order — Your API wallet balance is too low. Top up before retrying.
Client timeout before response — Your HTTP client gave up before the API returned. Set timeout to at least 90 seconds (180 recommended for some SKUs) for POST /orders. Retry with the same Idempotency-Key and body, or call GET /orders/{id} if you already have order_id. A timeout is not proof of failure.
404 on orders/check — Usually insufficient stock for the requested quantity, or invalid item_id. Lower quantity or pick another SKU.
Wrong endpoint for “stock” vs “order status” — Use POST /orders/check with item_id and quantity to check product availability. Use GET /orders/{id} to get the status of an existing order.

Getting help

Documentation: Docs home, API Reference.
Support: support@cardpluspay.com.
Terms: cardpluspay.com/terms-and-conditions.

← Security · Integration Guide · Appendix →