# 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:

```json
{
  "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.

> **Warning:** Without an `idempotency_key`, a write that timed out may or may not have happened. Do not retry it blindly: read the item back first, or send a key.