Common Error Codes

All errors are returned in the following shape (compatible with OpenAI / Anthropic error formats), so SDKs and clients can parse them automatically:

{
  "error": {
    "message": "Invalid or missing API key",
    "type": "authentication_error"
  }
}

HTTP Status Codes

Status	error.type	Meaning
401	authentication_error	API Key missing or invalid. Check that Authorization: Bearer <key> (or x-api-key) is set.
402	billing_error	Account balance is insufficient. Top up on the wallet page.
404	not_found_error	No model specified, or the requested model is not available. Use a supported model id.
429	upstream passthrough	Upstream rate-limited the request. Retry later or switch models.
500	configuration_error	Server-side routing config issue (auto-reported). If it persists, please contact us.
502	api_error	Failed to reach the upstream provider (transient network or upstream issue). Retry.
other 4xx / 5xx	upstream passthrough	Errors returned by the upstream provider (content moderation, malformed body, etc.) are forwarded as-is.

Typical Examples

401 — Missing or invalid key

{
  "error": {
    "message": "Invalid or missing API key",
    "type": "authentication_error"
  }
}

Fix:

• Ensure the request carries Authorization: Bearer <API_KEY> (OpenAI protocol) or x-api-key: <API_KEY> (Anthropic protocol).
• Confirm the key is still active on API Keys.

402 — Insufficient balance

{
  "error": {
    "message": "Insufficient balance",
    "type": "billing_error"
  }
}

Fix: top up on the wallet page.

404 — Model not found

{
  "error": {
    "message": "No provider for model 'gpt-x'. Available: claude-sonnet-4-6, gpt-5.3-codex, ...",
    "type": "not_found_error"
  }
}

Fix:

• Ensure model matches the model list.
• If you use the "key suffix" style (Cline / Kilo Code), make sure the format is sk-xxx-<provider>/<model>.

502 — Upstream connection failed

{
  "error": {
    "message": "Upstream connection failed",
    "type": "api_error"
  }
}

Fix: usually a transient upstream issue — retry. If it keeps happening, please contact us.

Other Notes

• Plugin cost estimates are off: Tools like Cline estimate costs using OpenAI list prices and don't know about platform discounts. Actual usage is always the wallet page.
• Streaming disconnected early: When the client disconnects mid-stream, the platform still bills the tokens reported by the upstream usage event, consistent with a normal completion.