When an agent gets stuck

Hydrant’s errors are blunt on purpose. Find the symptom, do the thing.

Before you start

• Get the exact error from your agent, not its summary of the error. Agents paraphrase. The code and the sentence matter.
• Open Settings › Agents in the workspace. Half of these are answered by one glance at the Connections list.
• If nothing works at all, including the website, rule us out first: Check service status.

Steps

A refused tool call comes back inside the tool result as error.code and error.message. Sign-in, rate-limit and maintenance failures are plain HTTP responses instead. The numbers below are the HTTP status, or its equivalent. Match the code, then the message.

unauthenticated (401): “Agent credential is unavailable.”

One message, on purpose, for every reason a credential stopped working: expired, revoked, mistyped, or the person who granted it left the workspace.

1. Look at the row under Connections or Agent keys.
2. Expired: sign in again from the client. Revoked or missing: approve again, or create a new key. See Reconnect, expire, revoke.

insufficient_scope (403): “This token lacks the required workspace permissions.”

The connection is read-only and the agent tried to write. Revoke it under Connections and approve again with read and write.

forbidden (403)

• Anything about members, keys, invitations or ownership. Those are browser-only. No agent can do them, whatever role you hold.
• A write an Admin could make but you can’t. The agent has your role. Workflow, labels, shared saved views, cycles and projects need an Admin. Who can do what.

not_found (404)

The issue, project or document doesn’t exist in this workspace, or it’s in the trash. A connection sees exactly one workspace, so an ID from another workspace is simply not found. Check which workspace the agent is connected to.

conflict (409)

• “This issue changed. Review the latest version before reapplying your draft.” Someone edited it after the agent read it. Re-read, review, then send a new command with a new request ID. Never auto-refresh and resend.
• “This request ID was already used for another command.” One UUID per command. The agent reused one.
• “Free allows 2 agent connections per workspace, keys and OAuth combined, and every slot is taken.” The plan’s limit, 20 on Solo Pro. Revoke unused keys and connections; each one frees a slot.
• The full rules: Writes that don’t bite.

rate_limited (429): “Agent request limit reached. Try again later.”

120 requests a minute per agent. The response carries Retry-After. Wait that long; hammering extends the wait. Retrying an accepted command with its original request ID doesn’t count.

unavailable, or 503: “Hydrant is paused for maintenance. Please retry later.”

Writes are paused or something broke on our side. A write may already have committed. Keep the original request ID and body, wait, and retry exactly that. Check service status for planned maintenance.

410: “This MCP endpoint is retired.”

The client is pointed at an old address. Use https://hydrant.dev/api/mcp.

What you should see

After the fix, ask the agent for a fresh read. The row under Connections shows a new last contact time, and the read carries the workspace you expect. That’s working.

If it goes sideways

Sometimes the client never gets as far as an error:

• The browser said “Nothing to approve.” The request went stale. Start again from the client.
• The browser came back to a localhost page that won’t load. The command-line tool stopped listening before you approved. Run its sign-in again and approve promptly.
• Codex signs in, then nothing. Upgrade to 0.154.0 or newer.
• No custom connector option in Claude. It depends on your Claude plan.

None of the above? Email bots@hydrant.dev with the error code, the sentence, roughly when it happened and which client you use. Leave out keys, tokens and private workspace content. We don’t need them and you don’t want them in an inbox.