On this page
Common errors
Errors any agent tool may hit when connecting to HiAPI, and how to fix them.
Each tool guide only lists errors specific to that tool. These can happen with any tool. Check the status code or keyword in the error first, then look it up in the table below:
| Error | Cause | Fix |
|---|---|---|
| 401 / invalid api key | The key is incomplete, has spaces before or after, or you copied the masked display value | Go to API Keys, click the copy icon, and copy the full HiAPI API key again |
| The error mentions balance, quota, or a spending limit | The account balance is too low, or this key’s spending limit is used up | Top up at Account balance, or raise this key’s spending limit on the API Keys page |
| 403 | This key has no permission for the model | Check the key’s group and permissions, see Authentication |
| 404 / model not available | The base URL has an extra or missing /v1, or the model name is misspelled | Check the URL against Base URL & protocols; copy the model name from the text model list |
| 400 does not support this endpoint | The tool’s selected protocol is not supported by this model | Try another protocol (for example, use Anthropic Messages for Claude), or switch to another model |
| 400 stream must be true / spinning forever | The model is streaming-only and the tool sent a non-streaming request | Turn on streaming in the tool. If the tool’s “Check” or “Test connection” button returns this error, ignore it and go by an actual chat |
| 429 | Too many requests or too much concurrency | Wait and retry, and run fewer tasks at once; if the error mentions a quota, follow the “balance, quota” row above |
| 500 / 502 / 503 | The model service failed temporarily | Wait a minute or two and retry; if it keeps happening, try another model first, then contact us |
| Timeout / interrupted response | The network or a proxy blocked the long-lived connection | Check network and proxy rules for api.hiapi.ai, then retry |
Check the request log before retrying
An agent task may already have finished on the server, with only the tool’s connection dropped. Before retrying, check Request logs to see whether this request succeeded and how much it cost, so you don’t pay twice for the same work.
Still stuck
Submit a ticket at Contact us with the information below; it helps us locate the issue faster:
- The time of the error (to the minute)
- The tool and version you used, for example Claude Code 2.1.284
- The model name and base URL
- The original error text or a screenshot
Mask the API key before taking a screenshot, and never send the key to anyone, including support.