Errors
| Status | Meaning |
|---|---|
| 400 | Bad request — unknown/unpriced model (model_pricing_missing), invalid body, charge would exceed max, or Venice rejected a quote (wrong duration / aspect / resolution for that model). Use exact catalog ids and model_spec.constraints from GET /api/v1/models. |
| 402 | Payment required — settle and retry identically |
| 404 | Unknown path (not on the gateway allowlist) |
| 409 | Payment already used |
| 410 | Upstream retired — Venice removed the path (currently POST /api/v1/video/transcriptions). No payment is taken. |
| 429 | Upstream daily budget exhausted (operator capacity), or Venice rate-limit. Venice typed reason / rateLimitType: RPM (requests/min), TPM (tokens/min), RPD (requests/day), FAILED_REQUESTS, UNSUPPORTED_FEATURE_REQUESTS. |
| 501 | Receiver or facilitator not configured |
| 502 | Upstream proxy failure or uncertain settle. After a successful settle, proxy timeouts/errors include PAYMENT-RESPONSE + x-aispace-payment: settled + x-aispace-payment-id (USDC already moved — not refunded). settle_uncertain means the facilitator errored after settle may have mined — do not retry the same payment. |
| 503 | Budget store unavailable in production, or Venice quote 5xx / timeout (not a bad request body) |
Error bodies are typically JSON { "error": "…" }. On settle failure you may receive a fresh 402 instead of a plain error — always prefer the latest challenge amounts.
Paid but undelivered
Settlement is final (pay then fulfill). If fulfillment fails after capture:
- Response is usually 502 with
PAYMENT-RESPONSE,x-aispace-payment: settled, andpaymentId/x-aispace-payment-id - Body includes
"settled": true— treat this as paid; do not sign a new payment unless you intentionally want to pay again - Check Base for the tx id before assuming the charge failed
Credit / refund for settled-but-undelivered work
On-chain settlement cannot be reversed by the gateway, but a charge that
settled yet never delivered is eligible for a service credit or refund.
“Undelivered” means the response was a non-2xx (typically 502) and the
body carried "settled": true — i.e. you paid but did not receive usable
output. It does not cover a 2xx response you simply dislike, or a
settle_uncertain where you must not retry (see 502 above).
To request a credit, email aispace.dev@proton.me with:
- the
paymentId/x-aispace-payment-id(the on-chain tx hash on Base), - the payer wallet address (EIP-3009
authorization.from), - the resource path and approximate UTC timestamp, and
- the response body/status you received.
We verify the settle against the facilitator record and the upstream Venice call, then issue a credit against future calls (or a USDC refund to the payer address for larger amounts). Verified settled-but-undelivered charges are credited in full. Typical turnaround is within 5 business days.