Handling errors

When something goes wrong, the Gateway answers with a status and a stable code. This page goes through the situations an agent meets in practice and what it should do in each. The full list of codes is in Error codes.

The rule of thumb#

• Read the code, not the message. Codes are stable; messages are for people and may change.
• denied means nothing was sent. Your system never saw the call. It's safe to fix the cause and call again.
• unknown means it may have happened. Never call a write again after an unknown.
• Tell the user. When a call can't go ahead, say so plainly and say what would help, such as asking an admin or approver.

401 when connecting#

The Gateway answers HTTP 401, with no result object, when it doesn't accept who is calling. For your own agents, check:

For a customer's agent on a Gateway set up for customer access, a 401 means the sign-in is missing, expired, or no longer allowed: the business blocked the agent, or the permission was withdrawn by the business or by the customer. The 401 carries a WWW-Authenticate header that tells the MCP client where to sign in again. Agent tokens (agt_…) don't work on these Gateways.

A wrong address, or the address of a hosted Gateway that was retired, gives HTTP 404. A request larger than 256 KB gives HTTP 413.

The call was denied#

The status is denied, and nothing reached your system.

Invalid arguments#

The code is invalid_arguments, and input_errors lists each problem with its path and its own code, such as unknown_field, invalid_decimal or mixed_script. The agent should correct those fields and call again. Common causes:

• a field the tool doesn't have (check the tool's input schema from tools/list);
• an amount written with thousands separators or a currency sign instead of a plain number like 1500.25;
• an identifier that mixes Latin and Arabic letters.

See Calling tools for the rules.

Rate limited#

The code is rate_limited. Each agent may make a set number of calls a minute, and so may each agent on each tool (60 unless your admin changed it). The count starts with the first call and resets a minute later.

Wait before trying again: at least a few seconds, and longer each time it happens. Don't retry in a tight loop; every refused call is recorded too. Outside agents are counted per customer, so one busy customer doesn't use up another's calls.

Daily quota used up#

The code is quota_exceeded. Your organization has used all its tool calls for the day. Calls are refused until midnight in the organization's time zone. Tell the user; retrying won't help today. An admin can see the counts on the Usage page. See Usage and limits.

A call that needs approval can also end rejected with code quota_exceeded, when the organization has asked for all the approvals it can that day.

Stale configuration#

The codes are stale_snapshot and no_valid_snapshot. The Gateway hasn't been able to sync with the Control Plane for too long, so it no longer trusts its copy of your policy for this kind of call. By default, writes are refused after 15 minutes without contact and reads after an hour. The tools list then shows only get_execution_status.

Try again later. If it lasts, an admin should check the Gateway on the Gateways page: when it last synced, and whether it can reach the Control Plane. See Gateways and sync. A Gateway in your network that was retired can no longer sync, so it ends up answering this way until it's uninstalled.

Busy#

The code is busy, with a message that ends "Retry shortly." A Gateway limits how many calls each organization can have running at the same time (see Limits and defaults), and refuses extra calls at once instead of queueing them. The limit is lower on the hosted Gateway, where organizations share it. Nothing ran and nothing was recorded. Wait a second or two and try again, with a growing delay if it repeats.

Rejected or expired#

The status is rejected or expired after a call waited for approval. Nothing was sent.

• approval_rejected: an approver, or the customer, said no. Don't ask again unchanged.
• approval_expired: nobody decided in time. Ask the user whether they still want it.
• policy_changed, tool_changed, tool_disabled, agent_disabled, person_removed or gateway_retired: the request was cancelled because something changed while it waited, such as a new policy or a changed tool, so it could no longer run. After policy_changed or tool_changed, if the user still wants it, call again: that starts a new request under the current settings. After the other codes, calling again won't work until an admin changes something (a tool or agent was switched off, the person no longer has access, or the Gateway was retired), so tell the user. Older Gateways report all of these as approval_rejected.
• approval_request_refused, or another code: the request couldn't be approved at all, for example policy_version_mismatch because the Gateway's policy was older than the one just saved. Calling again starts a new request under the current policy.

Failed or unknown#

Both mean the Gateway sent the call, or tried to. They're very different.

failed: it definitely didn't happen. The code says why:

• your system's own error code, or http_ and the status (such as http_404) when it gave none;
• unreachable, no_response or invalid_response: your system couldn't be reached, or a read got no usable answer;
• invalid_credentials_config, or codes starting with credential_ or token_: the Gateway couldn't sign in to your system. An admin must fix the connection;
• identity_unavailable: the connection must be told who each call is for, and the Gateway couldn't say. An admin must look at the connection;
• target_blocked: the call would go to an address the connection doesn't allow. An admin must look at the connection;
• tool_unavailable: the tool or its connection is no longer on the Gateway;
• after an approval, the codes of the final check, such as policy_changed, agent_disabled or tool_version_changed, sometimes several separated by commas: something changed after the request was approved and before it ran, so it wasn't sent.

A failed read can be tried again. A failed write can be tried again once the cause is fixed, for example after correcting the data your system objected to.

unknown: it may have happened. A write was sent but no reliable answer came back (codes such as no_reliable_response, response_too_large, unreadable_success_response, redirected, or server_error_ and the status). Your system may have created the record.

Related: Error codes · Calling tools · Limits and defaults

Still stuck? Contact support from the console.