Errors

OpenModels uses OpenAI-compatible JSON errors through the Alephant gateway. Use the HTTP status code for broad handling and use error.code when the response includes a stable machine-readable code.

Error response format

OpenModels account, billing, and usage errors can include request_id and retryable fields:

{
  "error": {
    "message": "KeyMarket account has insufficient available balance",
    "type": "key_market_error",
    "param": null,
    "code": "key_market_insufficient_balance",
    "request_id": "km_0123456789abcdef",
    "retryable": false
  }
}

Some gateway or upstream errors use the standard OpenAI-compatible shape and may not include request_id or retryable:

{
  "error": {
    "message": "Invalid credentials",
    "type": "invalid_request_error",
    "param": null,
    "code": "invalid_api_key"
  }
}

Fields:

For routed model requests, if you send an x-request-id header, the gateway can echo it in error.request_id. Otherwise, the gateway may generate a km_... request id. Early authentication, account, or upstream errors may not include a request id, so keep your own request id in client logs.

Error codes

Handle these responses today:

OpenModels-specific Key Market codes may appear in gateway responses. When present, handle them as follows:

Retry guidance

Use error.retryable as the primary retry signal when it is present. If error.retryable is missing, fall back to the HTTP status code and your own idempotency rules.

Do not automatically retry these errors until the user or system changes something:

• invalid_api_key
• key_market_key_invalid
• key_market_insufficient_balance
• key_market_spend_limit_exceeded
• key_market_model_not_available
• key_market_image_price_not_available
• key_market_upstream_not_supported

These errors may be transient. Retry them with backoff when error.retryable is true, or when your HTTP status and idempotency rules allow it:

• key_market_no_upstream_available
• key_market_usage_unavailable
• key_market_upstream_error
• key_market_upstream_timeout

HTTP 429, 502, 503, and 504 responses without a Key Market code may also be transient. For retries, use exponential backoff and a small maximum retry count. For production workloads, log your client request id, error.request_id when present, error.code, model ID, endpoint, and whether the request was streaming.

Common fixes

Example handling

async function callOpenModels(request) {
  const response = await fetch("https://api.getopenmodels.com/v1/chat/completions", request);
  if (response.ok) {
    return response.json();
  }
  const body = await response.json().catch(() => null);
  const error = body?.error;
  const code = error?.code;
  if (response.status === 401 || code === "invalid_api_key" || code === "key_market_key_invalid") {
    throw new Error("OpenModels API key is invalid. Create or rotate the key before retrying.");
  }
  if (code === "key_market_insufficient_balance") {
    throw new Error("OpenModels credits are insufficient. Add credits before retrying.");
  }
  if (code === "key_market_spend_limit_exceeded") {
    throw new Error("OpenModels monthly spend limit has been reached for this key.");
  }
  const retryable =
    error?.retryable === true || [429, 502, 503, 504].includes(response.status);
  if (retryable) {
    throw new Error(`Retryable OpenModels error: ${code || response.status}`);
  }
  throw new Error(error?.message || `OpenModels request failed with ${response.status}`);
}

Support

When reporting an error, include:

• Your client request id
• error.request_id, if present
• error.code, if present
• HTTP status
• Model ID
• Endpoint
• Whether the request was streaming
• Timestamp