Start with the server's own diagnosis: in the Windows app, Server → Network diagnostics → Test connectivity checks that the server is listening, whether the port is taken, the access setting, the network address and the Windows Firewall rule. For containers, the last lines of docker logs or kubectl logs usually name the problem.
Responses and what they mean
| Status | Code in the body | Meaning and fix |
|---|---|---|
| 401 | invalid_api_key | No key, or a wrong, revoked or expired one. Check the Authorization: Bearer header. |
| 402 | license_required | The request needs a plan this server does not have (for example a Pro-only model on Free). |
| 403 | forbidden | The key is not allowed this model or endpoint, or the request needs Allow server administration. |
| 404 | model_not_found | The model is not installed. List models with GET /v1/models; download with POST /v1/models/pull. |
| 404 | unknown_url | The path does not exist. Check for /v1 in the base URL. |
| 429 | rate_limit_exceeded | A rate limit, quota or the Free allowance. Wait for Retry-After. X-AISuite-Upgrade: 1 means a paid plan would lift it. |
| 501 | no_provider_configured | No engine for that kind of request (for example vision) is installed. |
| 503 | engine_starting | The engine is loading a model. Retry after Retry-After. |
| 503 | — | Every worker is busy, or the server is draining for an upgrade. Retry after Retry-After. |
The full list is in the error reference.
Other computers cannot connect
- Access must be set to a network option, and the server must have restarted (or the service been reinstalled) since.
- The server needs a paid licence and at least one API key. Without either it serves this computer only and says so on the Server page.
- Windows Firewall must allow the port. Use Add firewall rule in Network diagnostics.
- Use the address the Server page shows (the computer's LAN address), not
localhost. - Check the network profile: Windows blocks more on a network marked Public.
The Windows service does not start
- The Server page shows the reason Windows or the server reported. The service log is in the data folder's
logs. - "Needs reinstall" after changing access, port, HTTPS or rate limits: choose Install as service again.
- After an app update, choose Update service when the app asks.
- Port already in use: another program (often another local AI server) holds the port. Close it or choose another port.
Licence problems
| Log line or code | Fix |
|---|---|
unknown-license-key / exit code 4 | The key is mistyped or not ours. Copy it again from the purchase email. |
license-expired | Renew the subscription; the server activates again on its next start. |
seat-limit-reached | More workers are running than seats bought. Stop one or add seats. |
could not reach the licence server | Allow outbound HTTPS to registration.softwaretailor.com. A server with a valid cached lease keeps serving meanwhile. |
| Gateway refuses to start (exit code 2) | Gateway mode needs AI Server Commercial. |
Answers are slow
- The first request after start loads the model; later ones are faster.
- Check the GPU is used: the Models page and the engine log say whether a GPU was found. Without one, use smaller models.
- Long documents and many simultaneous users need memory for context; see sizing.
- Behind a proxy, turn off response buffering or streamed answers arrive all at once.
Streamed answers stop half-way
A proxy or load balancer is timing out or buffering. Allow read timeouts of at least 60 seconds and disable buffering for /v1/.
The gateway pool is empty
- Each worker's
bearer_tokeningateway.json(orworkerTokenfor DNS discovery) must be a key issued on that worker, not a client key. - Workers must be reachable from the gateway on their port, and
/readyzmust return 200. - Workers found by local network discovery are only used when their fingerprints are listed in
discovered_worker_fingerprints.
Collecting information for support
Include the server version (the X-AI-Server-Version header or the About page), how it runs (Windows app, service, Docker, Kubernetes), the X-Request-Id of a failing request, and the last 50 lines of the log. Logs are redacted, but read them before sending.
Questions
Third-party tools get 429 after a few requests on Free +
On Free, tools other than AI Suite apps share 10 requests a day and 1 per minute per client. Pro Personal or Commercial removes the limit.
The server says it is running but apps cannot find it +
Apps on the same computer find the server through a lock file in the shared data folder. Restart the server from the app; if you run the daemon by hand, start it without --data so it uses the same folder as the app.