Genie
Documentation

Errors & status codes

OpenAI-shaped error envelope across every /v1 endpoint.

Envelope

json
{
  "error": "human-readable message",
  "code": "snake_case_machine_code",
  "details": { "...": "optional context, varies by code" }
}

Common codes

401 Unauthorized

  • missing-key — no Authorization header.
  • malformed-header — header present but not Bearer <token>.
  • not-found — key not recognized.
  • revoked, expired, policy-not-found.

402 Payment Required

  • insufficient-balance — org credit balance is zero.
  • budget-cap-hit — a cap layer tripped. Body includes capLayer, capWindow, resetsAt.

403 Forbidden

  • inference-disabled — org hasn't enabled inference (see settings).
  • provider-policy / model-not-allowed — key's allowedModels rejects this model.

422 Validation

  • VALIDATION_ERROR — Zod parse failed. details carries field-level errors.

426 Upgrade Required

  • PROTOCOL_VERSION_UNSUPPORTED — fleet-protocol-v1 worker handshake mismatch (relevant only to runners, not API customers).

429 Rate Limit

  • rate-limit-exceeded — rateLimitRpm or rateLimitRpd hit. Retry-After header included.

5xx Server

  • fleet-unavailable — no compatible runner online; transient. Retry with backoff.
  • internal-error — unhandled. Tagged with a request id; include it in support tickets.