PrivateMind
Get API key

Troubleshooting

Common errors and what to do about them.

401 — Authentication failed

  • Missing header: Make sure you send Authorization: Bearer $PMIND_KEY on every request, not just the first one.
  • Revoked key: Revocation is immediate. If you get 401 after something worked before, check the key list in Settings → API Keys and look for a Revoked status.
  • Expired key: Keys have an expiry date. Look for an Expired status in the key table.
  • Wrong key format: The full token is <access_key_id>:<secret>, including the colon. Don't send just the first half or just the second half.

Quick check:

cURL 
curl -s -o /dev/null -w "%{http_code}\n" \
  "https://api.privatemind.com/v1/models" \
  -H "Authorization: Bearer $PMIND_KEY"

If this returns 200, your key is fine and the issue is in your application code.

403 — Forbidden

  • Wrong model: The model id you sent isn't in your org's allowed list. Check GET /v1/models and pick one from the list.
  • User-scoped endpoint: Conversations and sources APIs require a user key, not an application key. Call POST /v1/auth/exchange first.

429 — Rate limit

  • You're just fast: Wait a moment and retry. The key's per-minute limit resets every minute on a sliding window.
  • Need more headroom: Split traffic across multiple keys. Each key has its own rate limit.
  • Exponential backoff: 1s → 2s → 4s → 8s → max 30s with a random jitter. Don't retry forever; surface the error after 3-5 attempts.

402 — Budget exhausted

  • Key cap hit: You've spent the full budget on that key. Go to Settings → API Keys, find the key, and raise the budget cap.
  • Org cap hit: Your whole org has spent its monthly budget. Talk to your org admin.
  • Plan ahead: Read the usage block on every response and surface it in your own logs so you see spend building before it hits the limit.

400 — Bad request

Common causes:

  • JSON parse error: Check commas, braces, and quotes. Use an online JSON validator if you're unsure.
  • Unknown model id: The model id might have changed. Refresh your model list with GET /v1/models. Don't hard-code model ids.
  • Unsupported parameter: Check supported_parameters on the model. Not every model supports every sampling control.
  • Context exceeded: Your prompt + your max_tokens exceeds the model's context window. Reduce either one.

404 — Not found

  • Wrong base URL: If you're pointing at api.openai.com or a different deployment's URL, you'll get 404 on PrivateMind endpoints.
  • Wrong endpoint path: The endpoint is /v1/chat/completions, not /chat/completions without the prefix.
  • Model removed: A model you were using yesterday may have been replaced. Check the catalogue again.

"My model suddenly disappeared"

Models in the catalogue change as the platform upgrades. Use GET /v1/models before important jobs to see what's currently available. Never hard-code a model id without a fallback. The fast and reasoning aliases are safer because they always map to the current best model in that category.

Streaming stops mid-response

  • Proxy buffering: Make sure any proxy between you and PrivateMind (corporate firewall, load balancer) doesn't buffer the response body. Streaming needs unbuffered HTTP.
  • Client timeout: Your HTTP client might have a default timeout that's too short for long completions. Set it higher, or…
  • Switch to non-streaming: Make a single stream=false call if latency requirements are loose and buffering is unavoidable.

Getting weird or nonsensical output

  • Bad messages order: Make sure roles are 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 message blocks.
  • Wrong response_format: If you set response_format: { type: "json_object" } but the model doesn't support it (check capabilities.response_format), the output will be unpredictable.

Where next