Troubleshooting

Solve common issues when integrating with KushRouter.

Authentication errors (401)

Double-check that you are using the correct header:
- OpenAI-compatible routes: Authorization: Bearer $API_KEY
- Anthropic-compatible routes: x-api-key: $API_KEY
Verify the key is active in the dashboard and has remaining credits.

Validation errors (400)

Ensure stream is a boolean value, not a string.
Confirm all required provider-specific parameters are provided (e.g., max_tokens for Anthropic models).
Review the Schemas page for full validation rules.

Rate limits (429)

Requests are throttled per API key and IP.
Use exponential backoff with jitter and honor Retry-After when present (numeric seconds or HTTP-date).
Spread bursts and coordinate concurrency across workers.
Check usage dashboards for burst patterns.

Retryability quick guide

400/401/402/413 — non‑retryable; fix the request/auth/size first
429 — retryable with backoff; reduce concurrency; follow Retry-After
5xx — retryable with capped exponential backoff

Payload too large (413)

Compress prompts or split conversations into smaller batches.
For long-running jobs, consider the Batches API.

Tool calls missing arguments

KushRouter streams incremental tool deltas, but some providers emit final arguments only at completion. We inject a final delta to ensure downstream clients receive full JSON.
Verify your client handles both incremental and final tool call frames.

Provider-specific pitfalls

OpenAI Chat: ensure the final finish_reason chunk is handled, and when stream_options.include_usage=true, read the usage-only chunk before [DONE].
OpenAI Responses: tools require response.requires_action handling and a follow-up submit_tool_outputs call.
Anthropic Messages: always send max_tokens; set anthropic-version correctly (use vertex-2023-10-16 on Vertex AI).

Need more help?

Contact support.
Enable verbose logging in your SDK and capture request IDs when reporting issues.

Further reading

Error codes Generations lookup