Error handling
Status codes returned by the API and what to do about them.
Errors are returned as a JSON body with an HTTP status code.
Status codes
| Status | Meaning | What to do |
|---|---|---|
400 | Invalid request body or parameters | Check required fields and value types |
401 | Missing or invalid API key | Verify the Authorization header |
402 | Insufficient balance | Top up in Wallet |
403 | Model not permitted for your account | Choose an allowed model or request access |
404 | Unknown model or endpoint | List models via GET /v1/models |
429 | Rate limit or quota exceeded | Back off and retry |
500 / 502 / 503 | Upstream or gateway error | Retry later; if it persists, contact support |
Error shape
{
"error": {
"message": "Insufficient quota",
"type": "insufficient_quota"
}
}Retrying safely
- Retry only
429,500,502and503;400/401/402/403/404will not succeed on retry. - Use exponential backoff with jitter, and cap the number of attempts (3–5 is typical).
- Make requests idempotent where possible, so a retry cannot double-charge you.
async function requestWithRetry(input, attempts = 4) {
for (let attempt = 0; attempt < attempts; attempt++) {
const response = await fetch('https://www.tokenmoo.com/v1/chat/completions', input);
if (response.ok || ![429, 500, 502, 503].includes(response.status)) {
return response;
}
await new Promise((r) => setTimeout(r, 2 ** attempt * 200 + Math.random() * 100));
}
throw new Error('Request failed after retries');
}