Errors — Gamra

Every error uses the OpenAI envelope:

{
  "error": {
    "message": "Insufficient balance.",
    "type": "insufficient_quota",
    "code": "insufficient_quota"
  }
}

The codes#

HTTP	`code`	What to do
`401`	`missing_authorization`	No `Authorization` header.
`401`	`invalid_authorization`	Malformed header — expected `Bearer <key>`.
`401`	`invalid_api_key`	Unknown or revoked key. Prompt for re-authentication.
`403`	`account_inactive`	The account is not active. Contact us.
`403`	`model_not_allowed`	Your plan does not open this model. Change model or plan.
`402`	`insufficient_quota`	Empty wallet. Top up.
`402`	`spend_cap_exceeded`	Monthly cap reached. Raise or clear it.
`429`	`rate_limit_exceeded`	Honour the `Retry-After` header and retry.
`404`	`model_not_found`	Unknown model. Refresh the list from `/v1/models`.
`400`	`invalid_body`	Invalid request body.
`400`	`model_lacks_vision`	Image sent to a model without vision. Not billed.
`502`	`upstream_unreachable`	Transient upstream failure. Retry with backoff.

The order of the checks#

The checks run in a deliberate order: model access before balance. A plan that cannot use a model is a permanent condition, and telling someone to top up for a request that will be refused anyway is the wrong message in the wrong order.

Always log the request id#

Every response carries x-gamra-request-id. It is also the idempotency key the usage ledger records — without it, a disputed request cannot be found.