Errors

The error response shape and what 400, 401, and 429 mean.

When a request fails, the gateway returns a non-2xx status and a JSON error body. Handle it by reading the HTTP status first, then the code.

{
  "code": "invalid_request",
  "error": "invalid JSON body",
  "request_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

Field	Meaning
`code`	A stable, machine-readable slug; branch on this.
`error`	A human-readable message. Log it; don't parse it.
`request_id`	The id of the failed call. Log it.

Check code, not the wording of error, in your control flow: the message can change, the code will not. Errors and retries lists every code the API defines and which failures to retry.

const res = await fetch('https://api.cruxy.ai/api/v1/chat', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.CRUXY_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ model: 'kavi', messages: [] }),
})
 
if (!res.ok) {
  const { code, error } = await res.json()
  console.error(`request failed (${res.status}): ${code} - ${error}`)
}

Status codes

The authenticated endpoints (Chat, Embeddings, Rerank, and Moderations) share the same set of failures.

400 Bad Request

The request was malformed: invalid JSON, a missing required field, or a value the endpoint rejects. Fix the request; retrying it unchanged fails the same way.

401 Unauthorized

The code is always unauthorized: the Bearer key is missing, malformed, unknown, expired, or revoked, and each case gets the same answer. Check the Authorization header and the key itself; verify it with GET /api/v1/me.

429 Too Many Requests

A limit was hit. The code tells you which:

`code`	Meaning
`rate_limited`	Requests are arriving too fast. Slow down, then retry.
`budget_exhausted`	The account's budget is spent. Retrying won't clear it until the budget resets or is raised.

The two are distinct: rate_limited clears on its own once you ease off, while budget_exhausted is a spend ceiling that a retry alone won't resolve. Rate limits and budgets covers both, and the headers that tell you how much headroom is left.

The device-login endpoints use their own OAuth-style codes on 400 (authorization_pending, access_denied, expired_token, invalid_grant) rather than the generic error shape above. Those are covered in Get your API key.

Next steps

Errors and retries: every error code, and how to retry.
Authentication: resolve 401s.
Chat: where these errors surface most.
Changelog: when the API version changes.