When an agent gets stuck

Hydrant’s errors are blunt on purpose. Find the symptom, do the thing. Skip the part where the agent apologizes for three paragraphs.

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 Access list.
• If nothing works at all, including the website, rule us out first: Check service status (opens in a new tab).

Steps

A refused tool call comes back inside the tool result as error.code and error.message. Sign-in and per-agent rate-limit failures happen before any tool runs, so they arrive as plain HTTP responses instead. The numbers below are the HTTP status, or its equivalent. Match the code, then the message.

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 its row under Access, or in the collapsed Revoked group below it.
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. That includes recording which guidance it received and requesting an export. Revoke it under Access and approve again with read and write.

forbidden (403)

• Anything about members, keys, invitations, ownership or bylines. 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, cycles and projects need an Admin; labels and shared saved views do too unless member management is on. Who can do what.
• “Your current Playbook permissions do not allow this action.” Agents start read-only in the Playbook. The Owner grants more under Settings › Playbook. See Playbook and guides.

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.

validation (400 or 422)

The request itself was wrong: a missing field, an unknown stage, a Ready issue that isn’t refined. The message says which. Fix the input; resending it unchanged won’t help.

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.” You see this in the browser, when creating a key or approving a connection, not from a tool call. The plan’s limit; 20 on Solo Pro, and Team stops counting. Revoke unused keys and connections; each one frees a slot. Expired connections free theirs on their own. Plans and billing.
• “This delivery identifier is invalid or expired.” Task guidance deliveries last an hour. Read the guidance again with get_task_context, then record that.
• The full rules: Writes that don’t bite.

rate_limited (429)

• “Agent request limit reached. Try again later.” 120 requests a minute per connection or key, every request counted. The response carries Retry-After.
• “This workspace is limited to 600 writes per minute.” Everyone’s writes together, people included. The tool result carries retryAfter in seconds. An agent retrying an accepted command with its original request ID and body still gets its receipt; only new writes wait.

Wait that long. Hammering just burns the next window.

too_large (413)

A whole request must fit in 1 MiB, a description in 102,400 bytes, a comment in 20,480 bytes and a title in 300 characters.

unavailable, or 503

Something on our side didn’t answer. A write may already have committed: the message says “reconcile using the original request UUID and body”, and it means it. Keep the original request ID and body, wait, and retry exactly that. Check service status (opens in a new tab) while you wait.

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 Access 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.
• “We couldn’t check your client to open the approval page.” Hydrant couldn’t verify the client’s registration information. Start sign-in again from the client with a fresh link. If it still fails, use the support steps below.
• The browser came back to a localhost page that won’t load, or the client said “Timed out waiting for OAuth callback.” Your client may have stopped waiting for the browser. Restart its sign-in, open the new authorization link and keep the login running while you approve. Don’t reload the old callback or reuse the old authorization link. localhost, 127.0.0.1 and [::1] point to the computer running the browser. If your client reported “Timed out waiting for OAuth callback”, it stopped waiting; a local page that won’t load can have other causes. If a fresh attempt still fails, use the support steps below.
• “Dynamic client registration limit reached.” Too many new client sign-ups from your network in an hour. Wait, then sign in once.
• 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.