Error codes
When a call doesn't succeed, the agent gets a status and a code. The same code appears on the execution in Executions & audit. This page lists every code, grouped by where it comes from, with what to do.
Codes are stable, short and lowercase. The message next to a code is for people and may change, so build agents on the code. See Handling errors for how an agent should react.
Authentication (HTTP 401)
When the Gateway can't accept the caller, it answers HTTP 401 before anything else happens. The answer contains no code, so a caller can't probe which tokens exist, and nothing is recorded. On a Gateway for your customers' agents, the 401 also carries a WWW-Authenticate header that points the MCP client to Gatelion's sign-in.
| Cause | What to do |
|---|---|
No Authorization: Bearer header, or the token is unknown | Check the client's configuration. The header must be exactly Authorization: Bearer agt_…. |
| The token expired or was revoked | Issue a new token under Tools & agents → Agents. |
| The agent is switched off | Switch it on under Tools & agents → Agents, if that's intended. |
| The token was issued less than a sync ago | Wait about 15 seconds: the Gateway accepts new tokens after its next sync. |
| The Gateway has no configuration yet | Check under Gateways that it's registered and has synced. |
| An agent token on a Gateway for customers' agents, or a customer's access token on a Gateway for your own agents | Use the Gateway that matches the kind of agent. |
| A customer's access token is invalid or expired | The MCP client should refresh it, or the customer signs in again. |
| The customer withdrew the agent's permission, or you blocked the agent | The customer must sign in and give permission again. A blocked agent stays out until you approve it under Customer access. |
An MCP request larger than 256 KB gets HTTP 413 instead.
Denials before running
These come with the status Denied. Nothing was sent to your system.
| Code | Meaning | What to do |
|---|---|---|
gateway_not_ready | The Gateway has no configuration yet. | Wait for its first sync. Check it under Gateways. |
agent_unknown | The agent was removed from the Gateway's configuration after it connected. | Check the agent under Tools & agents → Agents. |
busy | The Gateway is already running as many calls as it allows at once for your organization. Not recorded. | Retry shortly. |
gateway_disabled | The Gateway is switched off, or your organization is suspended. | Switch it on under Gateways, if that's intended. |
quota_exceeded | Your organization has used its tool calls for today. | Wait until midnight in your organization's time zone, or ask Gatelion to raise the limit. See Limits and defaults. |
unknown_tool | No such tool for this agent: it doesn't exist, it's switched off, the environment has no policy yet, or the policy never lets this agent run it. | Check the tool's Available switch under Tools & agents → Tools, and your policy. |
on_behalf_of_not_allowed | The on-behalf-of person is missing, isn't one the agent may act for, or isn't active. | Send X-Gatelion-On-Behalf-Of with a user id the agent may act for. |
rate_limited | Too many calls in the last minute, by this agent or to this tool. | Slow down and retry after the minute. |
invalid_arguments | The arguments don't fit the tool. input_errors lists each problem. | Fix the arguments. See Input errors. |
policy_denied | A deny rule matched, or no rule matched. The message names the rule. | Change the policy if the call should be allowed. |
customer_confirmation_unavailable | The rule needs the customer's confirmation, but this agent acts for staff, not for a customer. | Set the rule's Who confirms to Your approvers ("approvers": "staff"), or don't use the tool from your own agents. |
no_valid_snapshot | The Gateway's configuration is missing or more than 7 days old. | Restore the Gateway's contact with the Control Plane. |
stale_snapshot | The Gateway hasn't heard from the Control Plane for too long: by default 1 hour for reads and 15 minutes for writes. An admin sets both per environment on Settings. | Restore contact. Calls work again after the next sync. |
get_execution_status answers with the status unknown and one of these codes when it can't look up the call:
| Code | Meaning | What to do |
|---|---|---|
not_found | No call with this id for this agent. An agent only sees its own calls, and a customer's agent only that customer's. | Use the execution_id from the original answer. |
invalid_arguments | execution_id isn't a UUID. | Pass the id exactly as you got it. |
Input errors
With invalid_arguments, each entry of input_errors has a path, a code and a message. The path is a JSON Pointer to the field, for example /max_total or /lines/0/quantity. An empty path means the arguments as a whole.
| Code | Meaning |
|---|---|
payload_too_large | The arguments are larger than 64 KB. |
invalid_json | The arguments aren't valid JSON, or are nested more than 32 levels deep. |
duplicate_key | The same field appears twice. |
unknown_field | The tool has no such field. |
invalid_text | The text contains invalid Unicode. |
invalid_decimal | Not a decimal number such as 1500 or 1500.25, or out of range. |
invalid_integer | Not a whole number. |
mixed_script | An identifier mixes Latin and Arabic letters. |
unsupported_script | An identifier uses letters other than Latin or Arabic. |
disallowed_character | An identifier contains a character that isn't allowed, such as an invisible one. Identifiers may use letters, ASCII digits and - _ . /. |
pattern | The value doesn't have the form the tool expects. |
required, type, enum, maxLength, minimum and others | The value breaks the rule of that name in the tool's input description. |
schema | The arguments don't match the tool's input description in another way. |
Execution codes
These come with Failed or Unknown: reconcile. A failed call didn't happen. An unknown one may have: see Executions and audit.
From your system
| Code | Status | Meaning | What to do |
|---|---|---|---|
| Your system's own code | failed | Your system refused the request and said why, in a code, error or error_code field of its answer. Gatelion passes on only that code, never the system's free text. | Depends on the code. Check your API's documentation. |
http_400, http_404, http_409 and so on | failed | Your system refused the request without a usable code. | Check the arguments, or the record they refer to. |
server_error_500, server_error_503 and so on | unknown | A write got a server error. It may still have happened. | Check your system before trying again. |
A read that gets a server error ends failed, with the system's code or http_500 and so on.
From the Gateway
| Code | Status | Meaning | What to do |
|---|---|---|---|
unreachable | failed | Your system couldn't be reached at all. Nothing was sent. | Check the connection's address, and that the Gateway can reach it. |
no_response | failed | A read got no usable answer in time. | Retry. If it keeps happening, raise the time limit. |
no_reliable_response | unknown | A write was sent but no reliable answer came back in time, or the connection dropped. | Check your system before trying again. |
redirected | unknown for writes, failed for reads | Your system answered with a redirect, which the Gateway doesn't follow. | Point the connection at the final address. For a write, check your system. |
response_too_large | unknown for writes, failed for reads | The answer was larger than the tool's limit. | Raise the limit in the API description, or return less. For a write, check your system. |
unreadable_success_response | unknown | A write got a success status, but the answer wasn't JSON. | Check your system. Make the operation return JSON. |
invalid_response | failed | A read got a success status, but the answer wasn't JSON. | Make the operation return JSON. |
interrupted | unknown for writes, failed for reads | The Gateway stopped while the call was being sent. | For a write, check your system. |
invalid_argument | failed | The arguments couldn't be put into the request the API description defines. | Check the arguments against the operation. |
target_blocked | failed | The address isn't one this Gateway may reach, for example a private address it wasn't allowed to use. | Check the connection's address and allowed hosts, and the Gateway's private networks. |
tool_unavailable | failed | The tool or its connection is no longer in the Gateway's configuration. | Check the tool and connection under Tools & agents. |
missing_request | failed | The tool has no request description. | Re-import the API description. |
identity_unavailable | failed | The connection needs to be told who the call is for, and the Gateway can't make that header. Nothing was sent. | Update the Gateway, and check the connection's settings. |
Approval codes
When a request doesn't run
| Code | Status | Meaning | What to do |
|---|---|---|---|
approval_rejected | rejected | A person rejected the request. A Gateway that hasn't been updated to the current version also reports this for a request Gatelion cancelled. | Don't retry unchanged. Ask the person who asked what should change. |
approval_expired | expired | Nobody decided in time. | Make the call again if it's still needed. |
approval_request_refused | rejected | The Control Plane refused to create the approval request. | Make the call again. |
When Gatelion cancels the request
The call ends Rejected with one of these codes when Gatelion cancelled the request because something changed and it could no longer run. This happens at once, when the change is saved, to requests still waiting for approval and to approved requests that haven't started running. Approvers see the request as Cancelled and can't decide it. Nothing was sent to your system.
| Code | What changed |
|---|---|
policy_changed | A new policy version was saved after the request was made. |
tool_changed | The tool's API description was re-imported, and the tool changed. |
tool_disabled | The tool was switched off, or a re-import removed its operation. |
agent_disabled | The agent was switched off. |
person_removed | The person the agent acted for no longer has access. |
gateway_retired | The Gateway the request came through was retired. |
If the call is still needed, make it again: it will be checked, and approved if needed, under the current settings. Gateways that haven't been updated to the current version report these as approval_rejected. See Approvals.
When the Control Plane refuses the request
The call ends Rejected with the Control Plane's own code.
| Code | Meaning | What to do |
|---|---|---|
policy_version_mismatch | A new policy was saved after the Gateway's last sync. | Make the call again after the next sync. |
tool_version_mismatch | The tool was switched off or changed. | Check the tool, then make the call again. |
approval_not_required | The current policy no longer needs approval for this call. | Make the call again. |
agent_not_authorized | The agent, its token or the customer's permission is no longer valid. | Check the agent and its token. |
on_behalf_of_not_allowed | The agent may no longer act for this person. | Check May act for on the agent. |
customer_confirmation_unavailable | The rule needs a customer, and this agent acts for staff. | See the same code under denials. |
gateway_disabled | The Gateway is switched off, or your organization is suspended. | Switch the Gateway on, if that's intended. |
quota_exceeded | Your organization has used its approval requests for today. | Wait until midnight in your organization's time zone, or ask Gatelion to raise the limit. |
When the final check refuses to run an approved request
The call ends Failed, or Expired when the approval ran out. The code names what changed. If several things changed, the code lists them, separated by commas.
Most of these changes cancel the request as soon as they're saved, so it ends rejected instead (see When Gatelion cancels the request). The final check catches whatever else changed before the call could run. If Gatelion cancelled the request just after the Gateway picked up the approval, the call ends here, failed, with the cancellation code, such as person_removed or gateway_retired.
| Code | Meaning |
|---|---|
policy_changed | A new policy version was saved after the request was made. |
tool_version_changed | The tool's API description was re-imported. |
tool_disabled | The tool was switched off. |
agent_disabled | The agent was switched off. |
gateway_disabled | The Gateway was switched off, or your organization was suspended. |
on_behalf_of_user_inactive | The person's account is no longer active, or the customer withdrew the agent's permission. |
expired, approval_expired | The approval's expiry time passed before the call could run. |
invalid_grant | The Gateway couldn't verify the permission it got. |
arguments_changed, agent_changed, policy_version_changed and other codes ending in _changed | The Gateway's record of the call doesn't match what was approved. |
In each case, make the call again if it's still needed: it will be checked, and if needed approved, under the current settings.
When an approver can't decide
Approvers see these in the console when they can't decide a request. The console explains each in words.
| Code | Meaning |
|---|---|
is_on_behalf_of_user | You're the person the agent acts for. |
is_agent_owner | You own the agent that asked. |
is_token_issuer | You issued the agent's token. |
not_approver_in_environment | You aren't an approver of this environment. |
customer_decides | Only the customer can confirm this request. |
approval_already_decided | Someone else decided first. |
approval_approved, approval_rejected, approval_expired | The request is no longer waiting: it was decided, cancelled or expired in the meantime. |
arguments_restricted | Only approvers and auditors of the environment can open the request. |
Credential codes
These come with Failed. They mean the Gateway couldn't sign in to your system, so nothing was sent. Even for writes, the outcome is never unknown.
| Code | Meaning | What to do |
|---|---|---|
credential_missing | The secret the connection names isn't in the Gateway's settings, or no sealed value was given. | Add the secret to the Gateway's settings, or enter it again under Change sign-in. |
credential_not_allowed_for_host | The secret may not be sent to this host. | Check the connection's allowed hosts, and the hosts the secret is bound to. |
credential_sealed_for_elsewhere | The sealed value was made for another connection or configuration, or in an older format. | Enter the value again under Change sign-in. |
credential_key_retired | The value was sealed to a key the hosted Gateway no longer has. | Enter the value again under Change sign-in. |
credential_sealed_unsupported | The connection has sealed values, but it's called by a Gateway in your network, which can't open them. | Use secret names for Gateways in your network. |
invalid_credentials_config | The connection's sign-in settings aren't valid, or this Gateway doesn't support them. | Check the sign-in settings, and update the Gateway. |
token_request_refused | Your system's token endpoint refused the Gateway's client credentials. | Check the client id and secret. |
token_response_invalid | The token endpoint didn't return a bearer access token. | Check the token endpoint's address. |
token_unavailable | The Gateway couldn't get a token from the token endpoint at all. | Check that the token endpoint is reachable and among the allowed hosts. |
Outside-agent codes
Codes that only concern your customers' agents:
| Code | Where | Meaning | What to do |
|---|---|---|---|
customer_confirmation_unavailable | Tool call, denied | A customer-approval rule was used by an agent that doesn't act for a customer. | See Denials before running. |
customer_decides | Console | Only the customer can confirm this request. | Nothing: the agent gave the customer the approval_url. |
invalid_client_metadata | Agent registration | The registration is missing a name, isn't a public client, or the Gateway accepts no more registrations. | Fix the registration, or raise the matter with the business. |
invalid_redirect_uri | Agent registration | Not 1 to 5 valid redirect addresses. | Fix the MCP client's redirect addresses. |
invalid_target | Sign-in | The token was requested for another Gateway. | Use the Gateway's own MCP address. |
access_denied | Sign-in | The customer didn't give permission, or sign-in failed. | The customer tries again. |
unauthorized_client | Token request | The agent is blocked or not yet approved by the business. | Wait for approval, or ask the business. |
invalid_grant | Token request | The code or refresh token is wrong, expired or already used. A reused refresh token also ends the customer's permission. | The customer signs in again. |
invalid_client | Token request | The agent isn't registered with this Gateway. | Check that the MCP client uses the Gateway it registered with, or let it register again. |
invalid_request, unsupported_response_type, unsupported_grant_type | Sign-in or token request | The MCP client asked in a way Gatelion doesn't support. Gatelion supports the authorization code flow with PKCE (S256) and refresh tokens. | Update or reconfigure the MCP client. |
rate_limited | Registration or sign-in | Too many requests from one address. | Retry later. |
A customer who withdraws permission, or an agent you block, gets HTTP 401 on its next request. See Authentication (HTTP 401).
In the console
The console shows a sentence, not the code. These are the codes behind the messages you're most likely to meet. Validation errors on a form, such as a value out of range, name the field instead.
Signing in
| Code | Meaning | What to do |
|---|---|---|
invalid_credentials | The email or password isn't right. A locked account gets the same answer. | Check them, or use Forgot your password?. After 5 wrong attempts, wait 15 minutes. |
email_not_verified | You tried to sign in before confirming your email. | Open the confirmation link, or ask for a new one. |
sso_required | Your organization requires its company login, and only admins may sign in with a password. The sign-in page switches to the company login. | Click Sign in with your company login. See Company sign-in (SSO). |
invalid_second_factor | The code or passkey after your password didn't work. Wrong codes count toward the lockout. | Try again, or use another method or a recovery code. |
locked | Too many wrong attempts. | Wait 15 minutes. |
second_factor_expired | The step after your password took longer than 5 minutes. | Sign in again from the start. |
second_factor_setup_required | Your role needs a second factor, and you haven't set one up. | Set one up on your Account page. |
user_inactive | Your account is no longer active, for example because an admin removed your access. The console signs you out. | Ask an admin of your organization. |
A company sign-in that fails brings you back to the sign-in page with the reason in words. See If a company sign-in fails.
Your account
| Code | Meaning | What to do |
|---|---|---|
confirmation_required | A change to your password or second factor needs you to confirm it's you first. | Enter your password and a code, a passkey or a recovery code when the console asks. |
not_confirmed | The password, or the code when you confirm it's you, isn't right. | Enter them again. |
weak_password | The new password is shorter than 8 characters or longer than 128, lacks an upper or a lower case letter, a number or a symbol, or is the same as your email address. | Choose another one. |
second_factor_required | A second factor is required for you, so you can't remove your last method or turn it off. | Add another method first. |
Administration
| Code | Meaning | What to do |
|---|---|---|
quota_exceeded | Adding this would pass one of your organization's usage limits. | Remove something unused, or ask Gatelion to raise the limit. See Usage and limits. |
hosted_full | Gatelion's hosted Gateways are at capacity, so a new hosted Gateway can't be added right now. | Try again later, or install a Gateway in your network. See Install a Gateway. |
own_account | You tried to remove your own access, or to reset your own second factor on People. | Ask another admin, or change your sign-in methods on Account. |
own_admin | You tried to take away your own Admin role. | Ask another admin. |
last_admin | The change would leave your organization without an admin. | Make someone else an admin first. |
too_many_invitations | An invitation was sent again too often: at most 3 times an hour. | Try again later. |
gateway_running | You tried to retire a Gateway that's still running. | Turn off its Running switch, then click Retire. See Retire a Gateway. |
not_unknown | You tried to settle an execution whose outcome isn't unknown, or that's already settled. | Nothing to do. See Unknown outcomes. |
invalid_policy | The policy can't be saved. The message says why. | See Validation errors on save. |
Company sign-in settings
| Code | Meaning | What to do |
|---|---|---|
mfa_not_confirmed | Company login can't be allowed or required until you confirm that it requires multi-factor sign-in. | Check that it does, then tick Our company login requires multi-factor sign-in. |
not_verified | Required can only be chosen after a successful Try company sign-in with the current settings. | Save, click Try company sign-in, then require it. |
not_configured | You clicked Test the settings before saving any. | Save the settings first. |
login_unreachable | Gatelion couldn't read your provider's published settings at the issuer. | Check the Issuer. See Provider notes. |
not_linked | You tried to unlink someone who hasn't signed in with the company login yet. | Nothing to do. |
Still stuck? Contact support from the console.