Errors

Every non-2xx response uses the same envelope:

{
  "error": {
    "message": "<human-readable description>",
    "type":    "<machine-readable code, see below>"
  }
}

Error types

Type	Status	When it fires
`auth_error`	401	Missing/malformed Authorization header, invalid API key, or key length > 256.
`plan_limit_error`	403	You hit a per-plan gate — e.g. a Free user requested a non-whitelisted model, or you tried to create a 6th API key on Pro. Error message includes the upgrade path.
`rate_limit_error`	429	Per-minute, per-day, or monthly cap exceeded. See Rate limits for the `retry-after` header and which window triggered.
`validation_error`	400	Malformed request body, query param out of range, oversized string, or invalid ISO-8601 timestamp.
`not_found`	404	Resource (workspace, API key, log) not found, or you're trying to delete something you don't own.
`upstream_error`	502	The LLM provider rejected the request or is unavailable. We sanitize the message so you won't see raw provider details — check the Logs page in the dashboard for the correlation ID.
`proxy_error`	500	Something broke inside ProxyLLM. We capture these in Sentry — please email contact@proxyllm.dev with the timestamp if you see this.

Correlation IDs

Every chat-completion response (success or failure) includes an x-proxyllm-request-id response header. Include it in support emails so we can find the exact log row.