Read the error body
{
"error": {
"code": "insufficient_balance",
"message": "Insufficient available credit",
"requestId": "example-request-id"
}
}The message above is illustrative. Base program logic on error.code and HTTP status, not exact message wording. Save requestId and the X-Request-ID response header for support. Never log API keys or installation secrets alongside them.
| HTTP status | Typical meaning | Next step |
|---|---|---|
400 | Invalid input | Check the schema and correct the request |
401 | Invalid, expired or revoked credentials | Check key, environment and account status |
403 | Missing scope or unavailable account operation | Check permissions with Akariq |
404 | Resource missing or not accessible | Verify the ID and ownership |
409 | Price, balance, reference or idempotency conflict | Inspect error.code; resolve the specific conflict |
429 | Request limit exceeded | Wait for Retry-After before trying again |
500, 503 | Server error or temporary unavailability | Back off; retain the original purchase request key |
Idempotency is part of the integration
Order and funding POST requests require Idempotency-Key. Use 8–128 characters from letters, digits, ., _, : and -; a UUID is a good choice.
Create and persist a key before sending the request. A retry of the same logical purchase must use the same key and identical body. The same key with a changed body produces 409 idempotency_conflict.
Each consumer order also needs a unique reference. Reusing a reference with a new key can conflict; changing both after a timeout can create an unwanted second purchase. Idempotency records are retained, so never recycle old keys for new orders.
Common conflicts
price_changed: refresh the plan and decide whether to accept the new price.insufficient_balance: fund the account or resolve the customer’s payment; a balance check alone does not reserve credit.idempotency_conflict: recover the original request; do not change its meaning.- A closed or expired funding/checkout session: inspect its payment state before starting a new session.
For network failures, retry with bounded exponential backoff and jitter. For a returned order ID, prefer tracking that order to resubmitting it. A delayed supplier response is not evidence that an order failed.