Get API key

Troubleshooting

View as Markdown

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 <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 the Authorization header.

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 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