Guide
Errors
Branch on error_code. Keep technical text away from your end customer.
What to show whom
| Field | For | Rule |
|---|---|---|
error_code |
Your bot logic | Stable string — switch / map to your own user-facing copy. |
message |
You / support only | Short technical hint. Log it. Do not paste it to the player in your shop bot. |
| Your UI text | End customer | Friendly only: wrong ID, try again later, contact support — never raw API payloads. |
Failed codes still cost 1 request each
(except a stock job that fails entirely with
NO_STOCK before any attempt).
Per code
| error_code | Meaning | Your bot | Show customer |
|---|---|---|---|
CHARACTER_NOT_FOUND |
Invalid player ID | Ask for correct ID; prefer lookup first | “Player ID not found” |
INVALID_CODE |
Format rejected | Do not retry same code | “Code invalid” (your stock: remove it) |
CODE_USED |
Already redeemed | Do not retry; mark used | “Code already used” |
RISK_CONTROL |
Temporarily blocked | Wait, then new job | “Try again in a few minutes” |
NO_STOCK |
Not enough KA BOT inventory | Restock or switch to source A | “Out of stock — try later” |
NETWORK_ERROR |
Temporary failure | Check code_returned on source B; retry policy on A |
“Temporary issue — we’ll retry” |
UNKNOWN |
Other | Log message + job_id; contact support |
“Something went wrong — support will help” |
HTTP
| Status | Meaning | Body (shape) |
|---|---|---|
400 |
Bad request | ambiguous_source, bad_codes, bad_player, empty |
401 |
Missing / invalid / revoked key | {"error":"unauthorized"} |
402 |
Wallet cannot cover PayG / overage | {"error":"payment_required"} |
403 |
No active API plan | {"error":"forbidden"} |
429 |
Rate limited — slow down | See Limits |