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.