Error Codes
You may encounter the following error codes when calling the KOPRouter API. Each lists its meaning, common causes, and solutions.
Authentication failed: the API key is missing, invalid, or expired.
**Common causes**
* Missing `Authorization: Bearer` header
* Misspelled key, or key deleted / disabled
* Key does not match the account
**Solutions**
Confirm the header and key, check the key's status on the console's API Keys page, and regenerate if needed.
Insufficient balance: prepaid balance or subscription allowance can't cover this request.
**Common causes**
* Prepaid balance exhausted
* Subscription allowance used up with pay-as-you-go disabled
* Estimated cost exceeds remaining allowance
**Solutions**
Top up on the console, or retry after the subscription allowance refreshes.
No permission: the account or user group can't access the model or resource.
**Common causes**
* Model not enabled for your user group
* User group / token quota exceeded
* IP or channel restricted
**Solutions**
Check your group permissions and quota, or ask an administrator to enable the model.
Resource not found: invalid model ID or endpoint path.
**Common causes**
* `model` is not in the `/v1/models` list
* Misspelled endpoint path
**Solutions**
Fill `model` with the `id` returned by `/v1/models` verbatim and check the endpoint path.
Rate limited: request rate exceeded the threshold.
**Common causes**
* Exceeded IP / token / user group rate limit
* Sudden high concurrency
**Solutions**
Lower the request rate or concurrency, and retry with exponential backoff.
Upstream error: the gateway failed when forwarding to an upstream provider.
**Common causes**
* Upstream provider temporarily unavailable
* Channel failure or timeout
**Solutions**
KOPRouter fails over automatically; if it persists, retry later or contact support.