Sallyport
MenuClose
Skip to documentation
DocumentationTroubleshooting

Troubleshooting

Find where a call stopped, read its answer code, and apply the fix.

On this page

Every refusal carries a code and a sentence that says what to do. When a person has to act, it also carries a link to the page that fixes it.

An MCP tool result puts the code in code, next to instruction. On /p/ an error comes as error.code and error.instruction, and a poll of a finished call that failed carries error_code. The console API answers with error.code and error.request_id.

Find the call

  • Every call has a call_id that starts with sp_c_. Open https://my.sallyport.cloud/activity?call=<call_id> to see it.
  • The call shows Agent, Binding, Key version, Rule, Journal and a Timeline of what happened.
  • Write to Settings, Support with the call_id, and with the request_id of a console API error.

See exactly what the agent sent and what came back

Open Activity, pick the call and press Open the whole request and answer. The call is there as it was, nothing hidden.

  • The request: method, full address, every header and the body. For SSH the command, for files the path and the content, for a database the statement and its values, for email the whole message.
  • A header the agent sent in the key’s own place, such as its own PRIVATE-TOKEN, stays in the list with its value. It is struck through and marked Replaced by the connection's key, not sent. The key Sallyport added never appears.
  • The answer: status, every header and the body. A long answer loads whole up to 1 MiB, and Download the full response saves all of it.
  • Requests stay as long as call history, 180 days by default. Answers and request bodies over 1 MiB stay 30 days, and after that the call says so.

A service is missing from the agent’s tools

  • Ask the agent to call list_access. It lists every service the agent may use and what waits for a person.
  • A new key goes to every active agent of its workspace and environment. An agent in Test never sees a Live key.
  • A connection removed from an agent’s Access list stays removed. Put it back with Add connection.
  • Past 40 tools, the tools of remote MCP servers leave the list. The agent finds them with search_tools and runs them with call.
  • A host outside the list works through http_request. The first call returns a link where you add its key.

Answer codes

CodeHTTPWhat happenedWhat to do
AUTH_FAILED401The token is wrong or revoked, or it is not an agent token.Create one with New token under Tokens on the agent’s page.
SUSPENDED423The agent, its workspace or the organization is paused.Press Resume agent on the agent’s page, or Resume calls in Settings, Danger zone.
SOURCE_IP_NOT_ALLOWED403The call came from an address outside the agent’s list.Edit Allowed IP addresses (optional) under Limits on the agent’s page.
ACCESS_REQUEST_CREATED404The agent has no key for this host.Open approve_url and add the key. The agent repeats the call.
SERVICE_NOT_CONNECTED424An OAuth connection is not signed in. Nothing was sent.Open connect_url and sign in. The agent repeats the call.
APPROVAL_PENDING202A person has not answered yet.Answer at approve_url. The agent continues with call_id.
APPROVAL_DENIED403A person refused. Nothing ran.The agent acts on the reason and does not repeat.
APPROVAL_EXPIRED410Nobody answered in time. Nothing ran.Repeat without call_id to ask again.
APPROVAL_SUPERSEDED409The rule or the key changed after the card opened.Repeat without call_id.
CALL_CONFLICT409Another call already used this approval.Make a new call.
CALL_NOT_FOUND404The call_id belongs to another agent or does not exist.Make a new call.
POLICY_DENY403The agent’s rule for this class is Denied.approve_url opens the agent’s page. Change the class on its Access list.
PATH_OUT_OF_PREFIX400The path is outside what the connection covers.Write the full path from the service’s documentation.
BAD_REQUEST400The call is malformed, and reason says how.The text names the fix. The list below covers the reasons a person fixes.
IDEMPOTENCY_CONFLICT409One idempotency_key came with different arguments.Use a new key.
IN_FLIGHT409The same call is already running.Wait retry_after_ms and repeat to get its result.
ALREADY_EXECUTED200A repeat got the first call’s result. The service was not called again.To run it again now, repeat with a new idempotency_key.
RATE_LIMITED429Too many calls in a short time.Wait retry_after_ms and repeat.
PLAN_LIMIT200The plan’s monthly calls are used up. Calls keep running, and MCP results carry this note.Open your plan in Settings.
UPSTREAM_ERRORThe service’s status, or 424The service answered with an error, or never answered.Read status and the body. The next table covers a missing answer.
UPSTREAM_TOO_LARGE424The answer passed the size limit.Narrow the request, or raise Largest answer from the service under Limits on the connection’s page, up to 512 MiB.
EGRESS_DENIED424The address is private (private_range), is Sallyport itself (self_host), Sallyport’s network cannot reach it (pin_mismatch), or the connection’s key was not saved for it (key_elsewhere). Nothing was sent.For private_range or self_host, use a public address. For pin_mismatch, send support the call_id. For key_elsewhere, ask the person who owns the key to add it again for this address.
OUTCOME_UNKNOWN424Sallyport cannot tell whether the service acted.Check the service before any repeat.
UPGRADE_NOT_SUPPORTED426An upgrade to a protocol other than WebSocket.Send the request without Upgrade, or open a WebSocket.
WEBSOCKET_REQUIRED426A poll of an approved WebSocket session, which runs only on a WebSocket.Open the WebSocket again with X-Sallyport-Call-Id.
UNAVAILABLE503Sallyport is briefly unavailable.Repeat after retry_after_ms.
INTERNAL500A defect in Sallyport. It is already recorded.Send support the call_id.

When the service did not answer

UPSTREAM_ERROR with a reason means no answer came back. side_effect is none when nothing reached the service and unknown when it may have.

Reasonside_effectWhat to do
dnsnoneRepeat in a few seconds. If it keeps failing, check the host name.
connectnoneCheck the address and repeat.
tlsnoneCheck the address. A repeat fails the same way until the certificate changes.
authenticationnoneSSH calls only. The server rejected the key or the user. Check both on the connection.
host_keynoneSSH calls only. The server’s key no longer matches the pinned one. Confirm it with the server’s owner, then see SSH commands.
ttfbunknownThe service did not start answering in time. Check it before any repeat.
timeoutunknownThe service did not finish in time. Check it before any repeat.
readunknownThe connection broke while the answer arrived. Check the service before any repeat.

Request errors a person fixes

Most BAD_REQUEST reasons are the agent’s to fix, and the text tells it how. These need a person:

  • not_https with console_url: the connection’s address starts with http://. Change it to https:// on the connection page.
  • mcp_binding, database_binding or email_binding: a /p/ call aimed at an MCP server, a database or a mailbox. Call its tools on the MCP endpoint instead. sftp_operation: a file call that does not name one operation plainly; detail says what to change.
  • missing_host: the connection covers every host of a service, so the call has to name one. On /p/, put the host right after the connection ID.

Console API errors

  • FORBIDDEN names the role it needs in details.required_role. Journal export needs an owner, or an admin or auditor of the whole organization with no narrower role in any workspace.
  • An API key cannot answer a card: a decision needs a person.
  • VALIDATION_FAILED names each wrong field in details.fields.
  • AUTH_FAILED means the session ended or the API key was revoked.

Replace a service key without a gap

  • Create a new key at the provider while the current one still works.
  • Open the key in Credentials, press Rotate credential, paste the new value and press Save the new credential.
  • Make one call through Sallyport. When it succeeds, revoke the old key at the provider.