Errors | JoyToken | Documentation

JoyToken model-call failures return OpenAI-compatible error objects. message is a readable reason; type is the more stable field for client-side handling.

Error response

1 {
2   "error": {
3     "message": "missing api key",
4     "type": "missing_api_key"
5   }
6 }

Chat Completions Errors

HTTP status	`error.type`	Common cause	Retry?
`400`	`invalid_request_error`	Body is not valid JSON, body exceeds 8 MiB, or `messages` is empty	No
`401`	`missing_api_key`	No API key was provided	No
`403`	`invalid_api_key`	API key is invalid or not `ACTIVE`	No
`403`	`policy_rejected`	Policy block, IP not allowed, model blacklist, tier not allowed, fixed model mismatch	No
`402`	`insufficient_quota`	Daily/weekly quota exceeded or current tier wallet balance is insufficient	No; adjust balance or policy first
`502`	`routing_error`	Router returned no usable model or routing service error	Short backoff retry
`502`	`upstream_error`	Provider invocation failed or downstream gRPC error was converted by gateway	Short backoff retry
`503`	`upstream_error`	Downstream service unavailable	Yes
`504`	`upstream_error`	Downstream deadline exceeded	Yes
`500`	`stream_error`	Current response writer does not support streaming	No; usually deployment/proxy issue

The OpenAPI definition keeps 429 for traditional rate-limit compatibility, but the current code path explicitly enforces quota, policy, and wallet precheck. Fixed QPS rate limiting is not a public capability yet.

Models Errors

GET /api/v1/models is exposed by front-gateway and does not require an API key. The most common failure is unavailable backend model service:

503 response

1 {
2   "code": 50300,
3   "message": "admin-bff not available"
4 }

Debug Fields

When a request fails, record these fields and query the same time window in Console logs / usage:

Field	Source
`X-Request-ID`	Request header, or gateway-generated internal request ID
`model` / `tier`	Request body
HTTP status	Response status code
`error.type` / `error.message`	Error response body
`X-DAOE-Used-Model` / `X-DAOE-Used-Provider`	Successful response headers, used to confirm actual routing
`metadata.billing`	Successful response body, used to confirm tokens and credits

Simple Retry Check

retry.ts

1 export function shouldRetryJoyTokenError(status: number, type?: string) {
2   if (status === 503 || status === 504) return true;
3   if (status === 502 && (type === "routing_error" || type === "upstream_error")) {
4     return true;
5   }
6   return false;
7 }