Velqa.dev API error codes and how to fix them
A rundown of the HTTP errors returned by the OpenAI-compatible API https://api.velqa.dev/v1, their most common cause and the fix to apply. Every error response contains a JSON error object with an explicit message.
Error table
| Code | Meaning | Common cause | Fix |
|---|---|---|---|
| 401 | Unauthorized | Missing, invalid or revoked key; malformed header | Check the Authorization: Bearer sk-... header. Create a new key in API keys if it was revoked. |
| 402 | Payment Required | Insufficient balance / budget: the key's monthly budget is exhausted, or the Boost balance is zero (audio, image, TTS) | Top up your balance or raise the key's budget. See Boost fallback and Rate limits. |
| 403 | Forbidden | Model not allowed for your key or plan (e.g. kimi-k2.6 on Starter, or a Boost-only model with no balance) | Check availability per plan in Models. Upgrade your plan or use Recharge Boost. |
| 400 | Bad Request | Invalid parameters: malformed JSON, missing field, out-of-range n or size (images), unknown voice (TTS) | Fix the request. For images: n ≤ 4, size ≤ 1024x1024. |
| 429 | Too Many Requests | Throughput exceeded (RPM/TPM) or context too large ("Too many tokens requested") | Retry with backoff. If it's the context, lower the context window in your tool — see opencode. Details: Rate limits. |
| 404 | Not Found | Model identifier does not exist or is misspelled | Use an exact model_id from the Models catalog. IDs are stable (e.g. kimi-k2.6, not kimi-k2). |
Best practices
- Always read the
error.messagefield: it states the exact cause (model, parameter, or limit involved). - Handle 429 with exponential backoff; handle 402 by monitoring your balance upfront.
- A 429 "Too many tokens requested" is not a throughput problem but a context size one: cap your agent's context window.