Errors

All BVE Gateway errors use the OpenAI error envelope format.

Error envelope

{
  "error": {
    "message": "Human-readable description of the error.",
    "type": "error_type",
    "code": "machine_readable_code"
  }
}

HTTP status codes

Status	Meaning
400	Bad request (invalid JSON, unsupported operation)
401	Missing or invalid credentials
403	Valid credentials but key is suspended or revoked
404	Route not found
413	Request body exceeds 10 MB
429	Rate limit exceeded
500	Internal server error
502	Upstream Fuelix error or unreachable

Error codes

Auth errors (401 / 403)

Code	Status	Description
missing_api_key	401	No Authorization header present
invalid_api_key	401	Wrong scheme, wrong prefix, or key not in DB
api_key_suspended	403	Key is suspended by an admin
api_key_revoked	403	Key has been revoked

Rate limit errors (429)

Code	Status	Description
rate_limit_exceeded	429	RPM, RPD, or monthly limit hit

Rate limit error messages indicate which limit was exceeded:

{
  "error": {
    "message": "Rate limit exceeded: requests per minute",
    "type": "rate_limit_error",
    "code": "rate_limit_exceeded"
  }
}

Possible messages:

• "Rate limit exceeded: requests per minute"
• "Rate limit exceeded: requests per day"
• "Monthly request limit exceeded"

Request errors (400 / 413)

Code	Status	Description
invalid_json	400	Request body is not valid JSON
unsupported_streaming_completion	400	stream: true used with /v1/completions
request_too_large	413	Body exceeds 10 MB

Server errors (500 / 502)

Code	Status	Description
internal_error	500	Unhandled exception in the gateway
upstream_error	502	Fuelix is unreachable or returned 5xx

Not found (404)

{
  "error": {
    "message": "Route GET /v1/unknown not found",
    "type": "invalid_request_error",
    "code": "route_not_found"
  }
}

Error handling example

import OpenAI from 'openai';

const client = new OpenAI({
  apiKey: 'sk-bve-YOUR_KEY',
  baseURL: 'https://api.bve.me/v1',
});

try {
  const response = await client.chat.completions.create({
    model: 'gpt-4o',
    messages: [{ role: 'user', content: 'Hello' }],
  });
} catch (err) {
  if (err instanceof OpenAI.APIError) {
    console.error(err.status, err.message);
    // err.error.code for the machine-readable code
  }
}