# Troubleshooting Common errors and what to do about them. Find your status code or symptom below. Each entry lists the usual causes and the fix. ## 400: Bad request Common causes: - **JSON parse error:** Check commas, braces and quotes. Run the body through a JSON validator if you're unsure. - **Unsupported parameter:** Check `supported_parameters` on the model. Not every model supports every sampling control. - **Context exceeded:** Your prompt plus your `max_tokens` is more than the model's context window. Reduce either one. ## 401: Authentication failed - **Missing header:** Send `Authorization: Bearer $PMIND_KEY` on every request, not only the first one. - **Revoked key:** Revocation is immediate. If you get `401` after something worked before, look for a **Revoked** status on the **API Keys** page. - **Expired key:** Keys have an expiry date. Look for an **Expired** status on the same page. - **Wrong key format:** The full token is `:`, including the colon. Send both halves. Quick check: ```bash curl -s -o /dev/null -D - "https://api.privatemind.com/v1/models" \ -H "Authorization: Bearer $PMIND_KEY" | grep -i -E '^HTTP|^x-privatemind-key' ``` The model list returns `200` with or without a valid key, so a `200` alone proves nothing. Read the `x-privatemind-key` header this prints: - `valid`: your key works, and the issue is in your application code. - `rejected`: the key is wrong, revoked or expired. - `none`: the request carried no key. Check that your code sends the `Authorization` header. [Verifying a key](https://docs.privatemind.com/api-keys.html#verifying-a-key) also covers a `403` from IP rules. ## 402: Budget exhausted - **Key cap hit:** You've spent the key's full budget. Create a new key with a higher cap and revoke the old one. - **Org cap hit:** Your whole org has spent its monthly budget. Talk to your org admin. - **Plan ahead:** Read your rows from `/v1/usage` to see spend building before it hits the limit. ## 403: Forbidden - **Address not allowed:** Your key's [IP rules](https://docs.privatemind.com/api-keys.html#restricting-keys-by-ip-address) don't allow the address you called from. - **Not allowed for this key:** The key may not call this endpoint, or your org has no access to this external provider model. Ask your org admin. ## 404: Not found - **Wrong base URL:** If you point at `api.openai.com` or another deployment's URL, PrivateMind endpoints return 404. - **Wrong endpoint path:** The endpoint is `/v1/chat/completions`, not `/chat/completions` without the prefix. - **Unknown or unavailable model** (`model_not_found`): The model id may have changed, a model you used yesterday may have been replaced, or your org may not have access to it. Refresh your model list with `GET /v1/models`, which lists only the models you can call. ## 429: Rate limit - **Too many requests in a minute:** Wait a moment and retry. The key's limit counts requests over a sliding 60-second window, so room frees up as older requests age out of it. - **Need more headroom:** Split traffic across several keys. Each key has its own rate limit. - **Exponential backoff:** Wait 1s, then 2s, 4s, 8s and so on up to 30s, with random jitter. Don't retry forever: surface the error after 3 to 5 attempts. ## "My model suddenly disappeared" The catalog changes as we upgrade the platform. Call `GET /v1/models` before important jobs to see what's available. Never hard-code a model id without a fallback. The `fast` and `reasoning` aliases are safer, because they always point to the current best model in their category. ## Streaming stops mid-response - **Proxy buffering:** Make sure no proxy between you and PrivateMind, such as a corporate firewall or load balancer, buffers the response body. Streaming needs unbuffered HTTP. - **Client timeout:** Your HTTP client's default timeout may be too short for long completions. Raise it. - **Switch to non-streaming:** If buffering is unavoidable and you can wait for the whole response, make a single `stream=false` call. ## Getting weird or nonsensical output - **Bad `messages` order:** Keep roles in a sensible sequence (`system`, `user`, `assistant`, `user`, `assistant`, …). Don't start with an `assistant` message. - **Empty messages:** A `user` or `assistant` entry with empty `content` confuses most models. Remove empty entries. - **Wrong `response_format`:** If you set `response_format: { type: "json_object" }` and the model doesn't support it (check `capabilities.response_format`), the output is unpredictable. ## Where next - [Authentication](https://docs.privatemind.com/authentication.html) for key format and rotation - [Errors](https://docs.privatemind.com/errors.html) for the full status code reference - [Rate limits](https://docs.privatemind.com/rate-limits.html) for limit math and backoff strategies