Errors

Map Ando API failures to product states before your app goes live. Users should know whether they need to reconnect Ando, update spend controls, wait for a rate limit, or retry later.

Account-owned provider routes

These errors apply to the ordinary Ando provider path that uses:

Authorization: Bearer <user-virtual-key>

401 Unauthorized

The user's Virtual Key is missing, invalid, expired, revoked, or pasted into the wrong provider field.

App state: Ando needs to be reconnected.

Recommended action: ask the user to paste a new Ando Virtual Key, then retest with GET /v1/models.

402 Payment Required

For Virtual Key routes, the user's Ando budget, spend cap, or available inference balance cannot cover the request.

App state: Ando spend limit reached.

Recommended action: tell the user to review their Ando spend controls or choose a smaller request. Keep the failed prompt in your app so the user can retry after the Ando account is ready.

403 Forbidden

The key may be valid, but the request is outside the key or connection policy. This can happen when a model is not available to that connection.

App state: Ando connection policy blocked this request.

Recommended action: refresh GET /v1/models, use an allowed model, or ask the user to check the Ando connection.

429 Too Many Requests

Rate limiting has been applied for the key, account, or route.

App state: Ando is rate limiting this connection.

Recommended action: back off, retry later, and avoid automatic retry loops that can spend user budget without progress.

5xx Errors

Ando or the upstream inference path failed temporarily.

App state: Ando is temporarily unavailable.

Recommended action: retry with exponential backoff and keep a request ID for support. Do not store raw Virtual Keys, payment credentials, prompt content, or response bodies in support logs.

Tempo MPP errors

For POST /v1/mpp/chat/completions, the endpoint returns MPP-specific error codes in the response body:

• payment_required: send an unpaid request first, then retry the identical request with Authorization: Payment <credential>.
• mpp_session_deposit_below_request_cost: the Tempo session deposit or available escrow is lower than the active voucher authorization. Open or top up a Tempo session with enough deposit to cover the current voucher bucket, then retry the same request.
• mpp_malformed_credential: the payment credential is missing, too large, not base64url JSON, or not an Authorization: Payment credential.
• mpp_method_unsupported: the credential is not a Tempo session payment.
• mpp_invalid_challenge: the challenge is expired, malformed, missing required fields, or not issued by Ando.
• mpp_body_digest_mismatch: the paid retry body does not exactly match the body bound into the challenge.
• mpp_request_quote_invalid: Ando could not derive a positive prepaid bucket quote for the request.
• mpp_request_exceeds_voucher_bucket: the quoted request would exceed the active voucher bucket before inference work.
• mpp_payment_verification_failed: the Tempo session credential could not be verified.
• mpp_payer_not_allowed: optional emergency/operator containment is enabled and the verified payer is not allowed.
• mpp_voucher_bucket_refresh_required: the accepted cumulative voucher bucket is exhausted, expired, or not yet authorized.
• mpp_reservation_failed: Ando could not reserve accepted voucher authorization before inference.
• mpp_commit_failed: Ando could not commit paid usage after inference, so no Payment-Receipt is emitted.
• mpp_session_close_unavailable: session close cannot run because the Tempo close signer or backend close path is not configured.
• mpp_session_close_failed: the Tempo session close credential could not be settled or recorded.
• mpp_streaming_unavailable: streaming is disabled for the first MPP rollout.

Troubleshooting MPP session deposit errors

If the response error is mpp_session_deposit_below_request_cost, the paid retry reached Ando but the verified Tempo session did not cover the active voucher authorization. Read the latest WWW-Authenticate: Payment challenge and open or top up a session with enough deposit for the current voucher bucket. The challenge may include a higher suggestedDeposit; that is a reusable-session hint, not Ando's hard protocol minimum.

Some Tempo clients can fail locally before sending the paid retry, for example with Deposit too low for request. In that case Ando cannot return an API error because no paid request reached the gateway. Treat it the same way: increase or top up the client's active session deposit enough to cover the voucher bucket, then retry the exact same request body.

Troubleshooting MPP voucher bucket errors

If the response error is mpp_voucher_bucket_refresh_required, the paid retry reached Ando but the accepted cumulative voucher bucket was exhausted, expired, or missing. Sign a fresh or higher cumulative Tempo session voucher and retry the exact same request body.

Troubleshooting MPP session close errors

If the response error is mpp_session_close_unavailable, the gateway has not been configured to submit Tempo close transactions or cannot reach the backend close recorder. The session remains open on Tempo. Configure the operator close signer and retry the close credential.

If the response error is mpp_session_close_failed, the close credential reached Ando but the Tempo close transaction or backend close record failed. Retry the close credential and include the session or channel references in operator escalation.