DocsError Handling

Error Handling

Possible errors from the Compresr API and Context Gateway.

SDK & API Errors

Authentication Errors (401)

Invalid, missing, or revoked API key. Ensure your key starts with cmp_.

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

Permission Errors (403)

API key lacks required permissions. Check your subscription tier.

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

Request Errors (400)

Missing required fields or invalid request format.

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

Validation Errors (422)

Values outside acceptable ranges 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. Implement exponential backoff.

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

Server Errors (500)

Internal server error. Retry or contact support if persistent.

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

Context Gateway Errors

Connection Errors

Cannot connect to upstream LLM API or Compresr API.

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

Configuration Errors

Missing or invalid configuration. Run context-gateway to reconfigure.

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

Agent Errors

Unsupported agent type or invalid agent configuration.

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

Compression Errors

Background compression failed. Original context used as fallback.

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

Port Conflict

Proxy port already in use. Set PROXY_PORT to a different port.

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

Best Practices

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