Common Errors

When an API request fails, check the HTTP status code first, then read the error response. The sections below cover the most common cases.

401 Unauthorized

This usually means the API key is missing, malformed, or no longer valid.

Check:

• The Authorization header is Bearer YOUR_AKAROUTER_API_KEY.
• The key comes from the AkaRouter console.
• The key has not been deleted or rotated.

402 Payment Required

This usually means the balance is insufficient or billing is unavailable for the account.

Check:

• Your wallet balance is enough.
• Your top-up order has been credited.
• Balance records do not show an unexpected recent usage or adjustment.

403 Forbidden

This usually means the account, model, or upstream access does not allow the request.

Check:

• The model name comes from the Model Status page.
• Your account can use that model or channel.
• You are not using the wrong regional endpoint.

404 Not Found

This usually means the request path is wrong. OpenAI-compatible chat requests should use:

https://api.akarouter.com/v1/chat/completions

If you use an SDK, confirm that baseURL is https://api.akarouter.com/v1, not the full /chat/completions path.

429 Too Many Requests

This usually means the request rate is too high or an upstream provider is rate-limiting requests.

Recommended actions:

• Reduce concurrency.
• Add more time between requests.
• Retry with exponential backoff.
• If it continues, contact support with the model name, time window, and request volume.

5xx

500, 502, 503, and 504 usually mean the API entry point or upstream model is temporarily unavailable.

Recommended actions:

• Retry briefly with a maximum retry count.
• Record the request time, endpoint, model name, and error response.
• Check the Model Status page for availability changes.
• Contact support if it continues.

Still Stuck

Prepare the request time, endpoint, model name, HTTP status code, and error response, then follow Contact Support.