# apifare error catalog

Every structured error is JSON: {"error": CODE, "message": human text,
...context}. The message always says what unblocks you. Codes:

## PAYMENT_REQUIRED (HTTP 402)
Balance too low. Relay human_readable to the user verbatim; retry the SAME call after top-up (or enable auto-refill at the enable_url).

## UNAUTHORIZED (HTTP 401)
Missing/invalid bearer. Get a token via POST /v1/signup; send it as Authorization: Bearer <token>.

## AGENT_KILLED (HTTP 403)
The operator killed this agent token. Only the operator can revive it (/revive in the operator Telegram).

## AGENT_REVOKED (HTTP 403)
Token permanently revoked. Ask the account operator for a new agent token.

## POLICY_DENIED (HTTP 403)
A per-agent cap or allowlist blocked the call BEFORE dispatch. The body says which rule and who can raise it.

## DAILY_CAP_REACHED (HTTP 429)
The account daily spend cap is hit. Resets 00:00 HKT; the operator can raise it via PUT /v1/policies.

## RATE_LIMITED (HTTP 429)
Too many requests (60/min per token; 10/min unauthenticated per IP). Back off and retry in a minute.

## UNKNOWN_API (HTTP 404)
No such slug. Discover slugs with GET /v1/search?q=.

## API_PAUSED (HTTP 503)
This capability is temporarily paused (spend alarm or provider issue). Check GET /status; try another slug.

## API_UNAVAILABLE (HTTP 503)
The capability is not configured on this deployment. Check /capabilities for what is live.

## BYOK_REQUIRED (HTTP 402)
This slug needs YOUR provider key. Ask for a one-time vault link (get_vault_link / POST /v1/keys/link) — never paste keys into chat.

## VAULT_KEY_MISSING (HTTP 409)
No vaulted key for this provider on this account. Same fix: one-time vault link.

## KEY_UNREADABLE (HTTP 500)
The vaulted key could not be decrypted. Re-vault it via a fresh link; contact support if it repeats.

## LINK_INVALID (HTTP 400)
Vault link malformed/expired (10-minute TTL). Request a new one.

## LINK_USED (HTTP 409)
Vault links are single-use. Request a new one.

## PROVIDER_ERROR (HTTP 502)
The upstream provider failed. Your debit is refunded automatically; retry, or check /status for a cluster.

## RESPONSE_TOO_LARGE (HTTP 502)
Upstream response exceeded the proxy cap (default 2MB). Narrow the request.

## PROXY_UNKNOWN_PROVIDER (HTTP 404)
No such proxy route. See PROXY routes in /llms-full.txt.

## PROXY_BAD_PATH (HTTP 400)
The proxy path failed safety checks (no .., no absolute URLs).

## REQUEST_CAP_REACHED (HTTP 429)
Daily request cap for an unpriced route. Resets 00:00 HKT.

## CONSENT_REQUIRED (HTTP 400)
Auto-refill needs the saved-card consent flow first: open the enable_url (/mandate?ref=...).

## BALANCE_CAP (HTTP 409)
The top-up would exceed the account balance cap ($100 default). Spend down first; over-cap Stripe payments park for review.

## EMAIL_EXISTS (HTTP 409)
Account exists. Use the existing token, or POST /v1/token/rotate if it was lost.

## SIGNUPS_PAUSED (HTTP 503)
Trial-abuse alarm paused signups. Try again later.

## NOT_CONFIGURED (HTTP 503)
This deployment lacks a required secret for the feature. The operator has been signaled.

## CONFLICT (HTTP 409)
The resource is already in the requested state (e.g. proposal already decided, refill already this period).

## FORBIDDEN (HTTP 403)
Founder/operator-only surface.

## BAD_REQUEST (HTTP 400)
The body/params are malformed; the message names the exact field shape expected.

## NOT_FOUND (HTTP 404)
No such resource, or not yours (tickets and mandates are account-private).