Documentation

Errors

Standard HTTP status codes. Every error body is JSON with the same shape: a top-level `error` object with `type` and `message`, plus optional extras (e.g. `balance_usd_micros` for 402). The legacy `detail` key is preserved for back-compat.

#Response shape

http

HTTP/1.1 402 Payment Required
Content-Type: application/json

{
  "type": "error",
  "error": {
    "type": "insufficient_credit",
    "message": "Pay-per-token balance depleted.",
    "balance_usd_micros": 0,
    "topup_url": "/tenant/billing/topup"
  },
  "detail": { "error": "insufficient_credit", "balance_usd_micros": 0, "topup_url": "/tenant/billing/topup" }
}

#Meaning

Code	Error type	Meaning
400	invalid_json	Request body was not valid JSON.
400	invalid_request	Schema validation failed — missing required field, wrong type, or unknown field.
401	unauthorized	Missing, malformed, or revoked API key.
402	insufficient_credit	Pay-per-token balance is zero. Body includes `balance_usd_micros` and `topup_url`.
402	no_subscription	Subscription-mode key without an active plan. Subscribe in the panel to unlock.
403	wrong_metering_mode	Pay-per-token-only route hit with a subscription key. Mint a pay_per_token key or use a tool-tuned route.
429	quota_exceeded	Subscription 24h window exhausted. Reset time in `x-powapi-quota-reset-at` (unix seconds).
500	internal_error	Unexpected server-side failure. Retry with backoff; if persistent, check status.powapi.io.
502	upstream_error	All routing candidates failed. Retry within 30s — the cascade reshuffles after that.