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_parameterson the model. Not every model supports every sampling control. - Context exceeded: Your prompt plus your
max_tokensis more than the model's context window. Reduce either one.
401: Authentication failed
- Missing header: Send
Authorization: Bearer $PMIND_KEYon every request, not only the first one. - Revoked key: Revocation is immediate. If you get
401after 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
<access_key_id>:<secret>, including the colon. Send both halves.
Quick check:
cURL
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 theAuthorizationheader.
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/usageto see spend building before it hits the limit.
403: Forbidden
- Address not allowed: Your key's IP rules 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.comor another deployment's URL, PrivateMind endpoints return 404. - Wrong endpoint path: The endpoint is
/v1/chat/completions, not/chat/completionswithout 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 withGET /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=falsecall.
Getting weird or nonsensical output
- Bad
messagesorder: Keep roles in a sensible sequence (system,user,assistant,user,assistant, …). Don't start with anassistantmessage. - Empty messages: A
userorassistantentry with emptycontentconfuses most models. Remove empty entries. - Wrong
response_format: If you setresponse_format: { type: "json_object" }and the model doesn't support it (checkcapabilities.response_format), the output is unpredictable.
Where next
- Authentication for key format and rotation
- Errors for the full status code reference
- Rate limits for limit math and backoff strategies