Docs Operations

Errors

What the endpoint returns when a request or a tool call fails, and what to do about it.

Failures come in two shapes. A request that never reaches a tool fails with an HTTP status. A tool that runs and fails returns a normal MCP result marked isError, so the model can read what went wrong.

HTTP errors

Status	Body	Meaning
`401`	`{"error":"invalid_token"}`	No credential, or one that is wrong, expired, revoked, used from a blocked IP address, or whose creator lost access. The answer is the same for all of these.
`404`	`{"error":"not_found"}`	Not the endpoint path.
`405`	JSON-RPC error `-32000`	A method other than `POST`.
`413`	`{"error":"payload_too_large","max_bytes":7340032}`	The request body is over 7 MiB.
`429`	`{"error":"...","retry_after_seconds":N}`	Too many requests without a valid credential. A `Retry-After` header carries the same wait.
`500`	`{"error":"server_error"}`	Something failed on Soontra’s side. Retry later.
`503`	`{"error":"service_unavailable"}`	A service Soontra depends on is down. `Retry-After` is 60 seconds.

When a signed-in connection has been replaced by a newer one, the 401 carries an error_description saying the connection is no longer active and asking the person to reconnect.

Tool errors

A failed tool call

{
  "isError": true,
  "content": [
    {
      "type": "text",
      "text": "{\"error\":\"This tool is not available for your key scopes.\"}"
    }
  ]
}

Message	Meaning	What to do
This tool is not available for your key scopes.	The credential lacks the scope the tool needs.	Add the scope to the key, or reconnect with a wider access level.
This action requires an owner or admin key.	The tool is for owners and admins.	Use a credential created by an owner or admin.
Invalid arguments: ...	An argument is missing, misspelled or out of range.	Fix the arguments. Unknown argument names are rejected.
Tool arguments too large.	The arguments are over the size limit.	Send less in one call, or use an upload URL for files.
Try again in N seconds.	A rate limit was reached.	Wait `retry_after_seconds`, then retry.
This content was rejected by moderation.	Text in a write was refused.	Change the text.
Moderation is unavailable right now. Please retry.	Writes are checked before they are saved, and the check could not run.	Retry shortly.
No cached analytics for this window yet. ...	Soontra has no stored results for that account and period.	In Soontra, ask Astrono for that account’s analytics once, which loads them. Then retry.
This MCP connection is no longer authorized. ...	Access was withdrawn while the call ran.	Reconnect, or ask an owner or admin.
The action failed. Please try again.	An unexpected failure.	Retry. If it was a write, see below.

An argument of the wrong type on a known parameter fails earlier, as JSON-RPC error -32602.

Retrying writes safely

Every write tool except soontra_files_createUploadUrl takes an optional idempotency_key: 1 to 128 characters from A-Z, a-z, 0-9, _, ., : and -. Send the same key with the same arguments and the write happens once, however many times you retry, for 90 days. Use a new key for a different write.