Alloneia
← Docs

Errors & retries

Every error from the gateway returns an OpenAI-shaped JSON body so existing clients keep working. Below is the exact catalog of codes l3k can emit, grouped by HTTP status.

Error shape

Always a top-level error object with message, type and code. The HTTP status drives retry semantics; the code is the precise reason.

{
  "error": {
    "message": "Your l3k balance is insufficient ...",
    "type": "insufficient_quota",
    "code": "insufficient_balance"
  }
}
400

Bad request

The body was missing or malformed. Don't retry without changes.

  • invalid_jsonRequest body wasn't valid JSON.
  • missing_model`model` is required.
  • missing_messages`messages` must be a non-empty array.
401

Unauthenticated

The Bearer key wasn't accepted. Don't retry — fix the key.

  • invalid_api_keyHeader missing, malformed, or not matching any key on file.
  • key_revokedKey was revoked or paused from the dashboard.
  • key_expiredKey passed its expires_at.
402

Payment required

Your prepaid balance can't cover the estimated cost of this request. Top up at https://www.alloneia.com/billing and retry.

  • insufficient_balancePre-charge estimate exceeds the balance left on the account.
403

Forbidden

Auth was fine but the key isn't allowed to call this resource.

  • model_not_allowedKey has a model whitelist (`allowed_model_slugs`) and the requested model isn't on it.
404

Not found

The model id is unknown or has been disabled.

  • model_not_foundNo active model matches the slug. Check `GET /v1/models` for the live list.
405

Method not allowed

Wrong HTTP verb on a known endpoint.

  • method_not_allowedUse POST for /v1/chat/completions and GET for /v1/models.
429

Too many requests

A per-key limit kicked in. Back off and retry.

  • rate_limit_exceededPer-minute rate limit on this key. Raise it from the dashboard or slow down.
  • spend_cap_exceededMonthly spend cap reached. Raise the cap or use a different key.
5xx

Server / gateway

Transient on our side or upstream. Safe to retry with exponential backoff.

  • service_unconfiguredGateway is missing required configuration.
  • model_cooldownModel is temporarily on cooldown after an upstream failure.
  • pricing_missingNo active pricing row for this model — admin must configure it.
  • gateway_unavailableBalance/limit check is temporarily unavailable.
  • gateway_under_maintenanceNo upstream node is currently connected for the requested model.
  • upstream_unreachableWe couldn't reach the execution node.
  • upstream_errorUpstream returned an error; the original message is forwarded verbatim.

Retry policy

Decisions you can hard-code on the client:

  • 5xx — retry up to 3 times with 250ms / 1s / 4s backoff. l3k already retries the upstream node internally before surfacing 5xx.
  • 429 — honor the message; rate_limit codes are safe to retry after the next minute, spend_cap requires user action.
  • Other 4xx — do not retry. Fix the request, key, or balance and try again.