Error Handling

The plugin provides structured error codes for every failure scenario with automatic retry logic for transient errors.

Error Codes

All errors are returned as AxiomClientError objects with a machine-readable code field. Tool outputs prefix the error message with [ERROR_CODE].

Code	HTTP Status	Description	Resolution
MISSING_WORKER_URL	—	Worker URL is not configured	Set workerUrl in plugin config
MISSING_API_KEY	—	API key is not configured	Set OPENROUTER_API_KEY env or apiKey in config
EMPTY_QUERY	—	Query string is empty or whitespace	Provide a non-empty query
INSUFFICIENT_MODELS	—	Fewer than 2 models specified	Add more models to the request or defaultModels config
AUTH_FAILED	401 / 403	API key is invalid or expired	Check your OpenRouter API key
RATE_LIMITED	429	Too many requests	Wait and try again later
CLIENT_ERROR	400–499	Client-side request error	Check request parameters
SERVER_ERROR	500+	Worker encountered an error	Check worker logs; will auto-retry
RETRY_EXHAUSTED	—	All retry attempts failed	Check network connectivity and worker health

Retry Logic

The client automatically retries failed requests with the following behavior:

Max retries: 2 (total of 3 attempts)
Retry delay: 1,000ms+ between attempts
Retried errors: 5xx server errors, network failures
Not retried: 401/403 auth errors, 400-499 client errors

Auth errors are never retried

If you receive an AUTH_FAILED error, the plugin will not retry. This prevents burning API quota with an invalid key. Fix the key and try again.

Timeout

Each consensus request has a configurable timeout (default: 120 seconds). The timeout is implemented via AbortController for clean cancellation.

Consensus with 7 iterations and 3 models typically takes 15\u201345 seconds
The first request may be slower due to model initialization (cold start)
If you consistently hit timeouts, consider reducing maxIterations or using fewer models

Input Validation

The plugin validates inputs before sending requests:

Empty query — the query string is trimmed and checked. Empty or whitespace-only queries are rejected with EMPTY_QUERY
Insufficient models — at least 2 models are required for consensus. If fewer are provided (and no defaults are configured), the error INSUFFICIENT_MODELS is raised
Missing configuration — workerUrl and apiKey are validated at client construction time

Network Errors

If the worker endpoint is unreachable, the plugin reports a connection error with the target URL. Common causes:

Worker is not deployed or is down
Incorrect workerUrl in configuration
DNS resolution failure
Firewall or proxy blocking the connection

Health check

The client provides a healthCheck() method that sends a GET request to /health on the worker. Use it to verify connectivity before running consensus queries.

Quick Troubleshooting

Symptom	Likely Cause	Fix
"Invalid API key"	Wrong or expired OpenRouter key	Regenerate key at openrouter.ai
"Rate limited"	Too many requests to OpenRouter	Wait 60s or upgrade your plan
Timeout after 120s	Too many models or iterations	Reduce maxIterations to 3–5 or use fewer models
"Connection error"	Worker endpoint unreachable	Verify workerUrl and check worker deployment
Low confidence results	Insufficient iterations or threshold too low	Increase maxIterations or lower dThreshold