DocsError Handling

Error Handling

Understand the possible errors from the Compresr API and Context Gateway, why they occur, and how to handle them.

SDK & API Errors

Authentication Errors (401)

Your API key is invalid, missing, or revoked. Check that your key starts with cmp_ and is active in your dashboard.

{
  "code": "authentication_failed",
  "message": "Invalid or missing API key"
}

Permission Errors (403)

Your API key does not have access to the requested resource or feature. Check your subscription tier and dashboard permissions.

{
  "code": "insufficient_permissions",
  "message": "API key doesn't have required permissions"
}

Request Errors (400)

Required fields are missing, parameter types are incorrect, or the request format is invalid.

{
  "code": "invalid_request",
  "message": "Missing required field: context"
}

Validation Errors (422)

Input values are outside acceptable ranges, such as an invalid compression ratio or unsupported model name.

{
  "code": "validation_error",
  "message": "Compression ratio must be between 0.2 and 0.9"
}

Rate Limit Errors (429)

Too many requests in a short time. Implement exponential backoff or batching to mitigate.

{
  "code": "rate_limit_exceeded",
  "message": "RPM limit exceeded",
  "details": {
    "limit_type": "rpm",
    "reset_at": 1640000000
  }
}

Server Errors (500)

Internal server errors. Retry the request or contact support if persistent.

{
  "code": "internal_error",
  "message": "An unexpected error occurred"
}

Context Gateway Errors

Errors specific to the Context Gateway proxy.

Connection Errors

The gateway cannot connect to the upstream LLM API or the Compresr API. Check that your API keys are valid and the services are reachable.

{
  "code": "gateway_connection_error",
  "message": "Failed to connect to upstream LLM API",
  "details": {
    "upstream": "api.anthropic.com",
    "reason": "connection refused"
  }
}

Configuration Errors

The gateway configuration is missing or invalid. Run context-gateway to re-run the interactive wizard, or check your ~/.config/context-gateway/.env file.

{
  "code": "configuration_error",
  "message": "Missing required configuration: COMPRESR_API_KEY"
}

Agent Errors

The selected agent type is not supported or the agent-specific configuration is invalid.

{
  "code": "agent_error",
  "message": "Unsupported agent type: unknown_agent",
  "details": {
    "supported_agents": ["claude_code", "openclaw", "opencode", "custom"]
  }
}

Compression Errors

The gateway failed to compress context in the background. The original uncompressed context will be used as a fallback. Check gateway logs for details.

{
  "code": "compression_failed",
  "message": "Background compression failed, using original context",
  "details": {
    "reason": "Compresr API timeout",
    "fallback": true
  }
}

Port Conflict

The gateway proxy port is already in use. Either stop the existing process or configure a different port.

{
  "code": "port_conflict",
  "message": "Port 8080 is already in use",
  "details": {
    "suggestion": "Set PROXY_PORT to a different port"
  }
}

Best Practices

  • Always check status codes before parsing response bodies
  • Implement retry with exponential backoff for 429 and 500 errors
  • Validate inputs client-side before sending to avoid 400/422 errors
  • Monitor gateway logs at logs/ for compression and connection issues
  • Use the SDK whenever possible — it handles retries and error parsing automatically