"Non-retryable client error (HTTP 400). Aborting." Six words that tell you nothing about what's wrong. Here are the six real causes from GitHub issues, ranked by how often they're the problem.
A user filed GitHub issue #26161 three days ago. Hermes v0.13.0. Gemini provider. First message: "hello." Response: GeminiAPIError [HTTP 400] Bad Request.
The model existed. The API key worked. Curl to the endpoint returned a valid response. But Hermes returned 400 on every attempt.
The error message gave zero diagnostic information. Just "HTTP 400" and "Bad Request." The user had to upload debug logs, agent logs, and gateway logs before anyone could help.
This is the most common runtime error in Hermes Agent. The official FAQ confirms it: "Setup completes fine, but the first chat attempt fails with HTTP 400." Here are the six causes, sourced from real GitHub issues, with the exact fix for each.
Cause 1: Model name mismatch (the most common, by far)
From the official Hermes FAQ: "Usually a model name mismatch. The configured model doesn't exist on your provider, or the API key doesn't have access to it."
The fix:
hermes config show | head -20 ... Check your provider and model ID.
hermes model ... Re-run model selection to pick from the provider's valid list.
hermes chat -q "hello" --model anthropic/claude-opus-4 ... Test with a known-good model to isolate whether the issue is model-specific.
The OpenRouter trap: Model IDs on OpenRouter look right but must match exactly. google/gemini-2-flash-preview is different from google/gemini-2.5-flash-preview. One character off = 400 error. And OpenRouter returns 400 (not 404) for invalid model IDs, which is confusing.
The diagnostic shortcut: If hermes chat -q "hello" --model anthropic/claude-opus-4 works but your configured model doesn't, the problem is 100% the model ID. Fix: hermes model and select from the list.
Cause 2: Tool schema incompatibility with provider (P1 bug)
GitHub issue #13927: "When running Hermes Agent v0.10.0 with OpenRouter as the provider, all API calls return HTTP 400 regardless of the model selected."
What happens: Hermes sends 28 tool definitions by default. Some providers reject the tool schema format. Every model on that provider fails. The error looks like a model problem but it's a tool compatibility problem.
How to diagnose: If every model on the same provider returns 400, but the same model works on a different provider (e.g., Anthropic direct works but Anthropic via OpenRouter doesn't), the tool schema is the issue.
The fix: Update to the latest Hermes version (v0.13.0+ fixed most schema issues). If updating isn't an option, reduce tool count: temporarily disable non-essential tools in your config to narrow down which tool schema the provider rejects.
For the broader comparison of how different agent frameworks handle provider compatibility, our comparison covers the provider integration differences.
Cause 3: Dual authentication headers on Gemini (a real bug)
GitHub issue #7893: "HTTP 400 'Multiple authentication credentials received' when using native gemini provider."
What happens: Hermes's gemini provider injects an x-goog-api-key header. Simultaneously, the underlying OpenAI Python SDK injects an Authorization: Bearer header. Google's API rejects requests with both headers as ambiguous credentials.
The fix: Generate a standard Google Cloud API key (starts with AIza...). Add GEMINI_API_KEY=your_key to ~/.hermes/.env. If using a Vertex AI key (starts with AQ.Ab8...), switch to the standard key format. The Vertex key format triggers the dual-header bug.
Cause 4: Missing reasoning_content for Kimi models
GitHub issue #13848: "When using kimi-for-coding with Hermes Agent, any session that triggers tool calls becomes permanently broken."
What happens: Kimi models with thinking enabled require a reasoning_content field in assistant messages containing tool calls. Hermes doesn't include this field. The first tool call succeeds. The corrupted message stays in conversation history. Every subsequent turn replays it and gets 400.
The fix: Start a new session (hermes chat --new). The corrupted history is session-specific. For a permanent fix, switch to a different model for Kimi tool calls, or wait for the upstream fix (the issue is tagged P1).
If debugging provider-specific auth headers, tool schema incompatibilities, model name formats, and session corruption from missing fields sounds like more API troubleshooting than agent building, BetterClaw handles provider compatibility at the platform level. 28+ providers. Model switching from a dropdown. No schema debugging. No auth header conflicts. Free tier with 1 agent and BYOK. $19/month per agent for Pro.
Cause 5: OpenRouter model requires paid plan or credits
From the official FAQ: "A 400 from OpenRouter often means the model requires a paid plan or the model ID has a typo."
The fix: Log into your OpenRouter dashboard. Check your credit balance. Some models (Opus, GPT-5.5) require a minimum credit balance. Free-tier OpenRouter accounts can't access all models. Add credits or switch to a free model (google/gemini-2.5-flash is free on OpenRouter).
Cause 6: Oversized request payload
What happens: Your conversation history + system prompt + 28 tool definitions exceeds the provider's maximum request size. The provider returns 400 instead of a context-length error.
The fix: Start a new session to clear accumulated history. Or reduce tool count. Or switch to a model with a larger context window. The Deploy Hermes guide recommends: "shrink the payload if needed, and rerun a minimal request before restoring complexity."
The diagnostic checklist (run this before anything else)
Step 1: hermes config show | head -20 ... What provider and model are configured?
Step 2: hermes chat -q "hello" --model anthropic/claude-opus-4 ... Does a known-good model work?
Step 3: Does the error happen on all models or just one? All models = provider/tool issue (Causes 2, 3, 5). One model = model-specific (Causes 1, 4, 6).
Step 4: hermes chat --new ... Does a fresh session fix it? Yes = corrupted history (Cause 4). No = configuration issue.
Step 5: Check provider dashboard for credits, billing, and model access.
The 400 error is Hermes's most common runtime failure. The error message is always the same: "Non-retryable client error (HTTP 400). Aborting." But the cause is one of six different things, and the fix depends entirely on which one you're dealing with. Diagnose first. Fix second. Don't guess.
If you want an agent platform where provider errors are handled at the platform level and you never see raw HTTP status codes, give BetterClaw a try. Free tier with 1 agent and BYOK. $19/month per agent for Pro. 28+ providers. Smart error handling. The provider compatibility is ours. The agent conversations are yours.
Frequently Asked Questions
What does Hermes Agent Error 400 mean?
HTTP 400 in Hermes means the API provider rejected the request as malformed. The six most common causes: model name mismatch (most frequent), tool schema incompatibility, dual authentication headers on Gemini, missing reasoning_content for Kimi models, insufficient OpenRouter credits, or oversized request payload. The error message is always the same regardless of cause, so diagnosis requires checking which cause applies.
How do I fix "Non-retryable client error (HTTP 400)" in Hermes?
Start with hermes config show to verify your provider and model ID. Test with a known-good model: hermes chat -q "hello" --model anthropic/claude-opus-4. If the known model works, your configured model ID is wrong. Run hermes model to select from the valid list. If all models fail, the issue is provider-level (tool schemas, auth headers, or credits).
Why does Hermes return 400 on every model with OpenRouter?
Two possible causes. GitHub issue #13927 documents a tool schema incompatibility where Hermes's 28 default tools use a format OpenRouter rejects. Fix: update to v0.13.0+. Second possibility: your OpenRouter account lacks credits. OpenRouter returns 400 (not 402/403) for billing issues. Check your OpenRouter dashboard for credit balance.
Why does Gemini return "Multiple authentication credentials received" in Hermes?
GitHub issue #7893. Hermes's gemini provider injects an x-goog-api-key header while the OpenAI SDK also injects a Bearer token. Google rejects the dual credentials. Fix: use a standard Google Cloud API key (starts with AIza...) instead of a Vertex AI key (starts with AQ.Ab8...). This was fixed in later versions but persists for some key types.
Does BetterClaw have the same 400 error issues?
No. BetterClaw handles provider compatibility at the platform level. Model switching is a dropdown selection. Provider authentication is managed. Tool schema compatibility is tested before deployment. You don't see raw HTTP status codes or debug API-level errors. Free tier with 1 agent and BYOK. $19/month per agent for Pro.
