Error Handling — Compresh Docs

Compresh is a transparent proxy — errors from your upstream provider (OpenAI, Anthropic, etc.) are forwarded to you as-is, with the same status codes and response bodies. This section covers Compresh-specific errors that originate from the proxy layer itself.

Error response format

All Compresh-originated errors follow this format:

{
  "error": {
    "message": "Invalid or missing API key",
    "type": "authentication_error",
    "code": "invalid_api_key"
  }
}

Compresh error codes

Status	Meaning	What to do
`401`	Invalid or missing API key	Check that your `Authorization` header contains a valid `comp_` key. Make sure the key hasn't been revoked.
`403`	Key deactivated or insufficient balance	Your key is valid but your account is deactivated or has no remaining balance. Top up at the dashboard.
`429`	Rate limit exceeded	You've hit your per-key rate limit. Wait until `X-RateLimit-Reset` or implement exponential backoff. See Rate Limits.
`500`	Internal proxy error	Something went wrong inside Compresh — the upstream provider is fine. Your request was still forwarded to the provider. Retry if needed. If persistent, check status.compre.sh.
`503`	Upstream provider unreachable	Compresh couldn't reach your configured provider. Check your provider's status page. This is not a Compresh issue — the upstream is down or unreachable.

Upstream errors

Errors from your LLM provider are passed through unchanged. For example:

OpenAI 400 for malformed requests
OpenAI 401 for invalid provider keys
Anthropic 400 for exceeding max tokens
Any provider-specific rate limits (separate from Compresh rate limits)

You can distinguish Compresh errors from upstream errors by checking the error.type field. Compresh errors use types like authentication_error, rate_limit_error, and proxy_error. Upstream errors retain their original format.

Tip

A 500 from Compresh doesn't mean your request failed at the provider. In most cases, the request was already forwarded successfully — only the compression metadata step had an issue. Check your provider's dashboard to confirm.

Handling errors in code

import openai

client = openai.OpenAI(
    api_key="comp_your_key",
    base_url="https://api.compre.sh/v1"
)

try:
    response = client.chat.completions.create(
        model="gpt-4o",
        messages=[{"role": "user", "content": "Hello"}]
    )
except openai.AuthenticationError:
    # 401 — check your Compresh API key
    pass
except openai.RateLimitError:
    # 429 — back off and retry
    pass
except openai.APIStatusError as e:
    # 403, 500, 503 — check e.status_code
    print(f"Status ${e.status_code}: ${e.message}")