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.

Code	Meaning	What to do
400	Bad request	Invalid parameters, insufficient balance, or out of stock. Check request body (e.g. item_code, quantity). Verify stock with POST /orders/check first.
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.
422	Validation error	Invalid format (e.g. missing required field, wrong type). Check the request against the API Reference.
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.

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 — Item may be out of stock or balance insufficient. Call POST /orders/check before checkout and GET /balance to confirm balance.
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.