Astralane / Developers

Errors, limits, and idempotency

Structured errors explain why a request was rejected or could not complete.

Error envelopes

Chat and Responses return an OpenAI-style error with message, type, code, and param. The public Messages route uses Messages-compatible streaming events, but some pre-stream failures still use the shared OpenAI-style envelope; validate client handling.

Example

{"error":{"message":"Insufficient wallet balance.","type":"billing_error","code":"insufficient_balance","param":null}}

Common responses

400 invalid payload; 401 invalid key/session; 402 insufficient funds; 403 scope or policy denial; 409 repeated/idempotency conflict; 413 request too large; 429 request or concurrency limit; 502 invalid or failed upstream; 503 no eligible route or service unavailable; 504 request deadline.

Idempotency

Inference accepts Idempotency-Key. A repeated persisted request returns 409 and the known request ID rather than replaying a response, because responses are not stored. Checkout requires the header. Stripe and wallet funding have independent database uniqueness protections.

Budgets and time

Key request/day and spend/day/month windows use UTC. All active reservations conservatively count toward current spend limits, including those spanning a boundary. Redis failures deny admissions rather than bypassing enforcement.

Handoff release

Native core and mock HTTP checks have run. Full dependency install, PostgreSQL/Redis integration, production builds, and browser flows still require local verification. See the repository verification report before deployment.