> ## Documentation Index
> Fetch the complete documentation index at: https://docs.rippit.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Errors

> What a failed MCP tool call, Bulk API request or CLI command returns, what each status means, and when a retry is safe.

Each interface reports failure in its own shape, with the same HTTP status meanings underneath.

| Interface | A failure looks like |
| - | - |
| MCP tools | A tool result with `isError: true` and one text block |
| Bulk API | An HTTP status with a JSON body that has a `detail` field |
| Rippit CLI | A nonzero exit status, and with `--format json` one JSON object on stderr |

## MCP tools

A failed tool call returns a normal MCP result with `isError: true`. Its one text block says what failed, the status behind it, what to do next, and a reference id:

```json theme={null}
{
  "isError": true,
  "content": [
    {
      "type": "text",
      "text": "reading table was rate limited (status 429). Wait before retrying. Reference: 5f0c1c1e-8a53-4c0b-9a39-0d3f0a1b7c11."
    }
  ]
}
```

Quote the `Reference` id when you ask Rippit about a failure. It identifies the exact request.

| Status | Meaning | What to do |
| - | - | - |
| `400` | The arguments have a valid shape but refer to something Rippit rejects. | Check the ids and values. The same call fails again. |
| `401` | The sign-in or token is no longer accepted. | Sign in again, or reconnect Rippit in your assistant. |
| `402` | The workspace reached its AI spend limit or is out of Credits. | See [Billing and Credits](https://docs.rippit.com/billing.md). |
| `403` | The user or workspace is not allowed to do this. | A retry does not help. Some operations need a workspace admin. |
| `404` | An id in the call matches nothing you can see. | Look the id up again, for example with `list_data_sources`. |
| `422` | The service does not accept one of the values. The message names the field. | Fix the value. The same call fails again. |
| `429` | The call was rate limited. | Wait a second and retry. See [Rate limits](https://docs.rippit.com/api-reference/rate-limits.md). |
| `504` | The call timed out. | For a read, ask for fewer rows or columns, or a narrower filter. |
| `5xx` | A Rippit service error. | Retry a read. Check before repeating a write. |

Arguments that don't match a tool's schema are rejected before the tool runs, with text that starts `Input validation error` and describes each problem.

### When a retry is safe

Reads and any call that returned `429` are safe to retry. A write that timed out or returned `5xx` may have taken effect, so check before repeating it. [Idempotency and retries](https://docs.rippit.com/api-reference/idempotency.md) lists which operations are safe to repeat and how to check.

### Connection errors

Before any tool runs, the server checks the request's sign-in. These failures are plain HTTP responses with a JSON body and an `x-request-id` header:

```json theme={null}
{
  "error": "unauthorized",
  "reason": "missing_token",
  "message": "Rippit needs a signed-in Rippit account. MCP clients sign in with OAuth on first use. If the user has no account yet, help them create one, then reconnect.",
  "mcp_url": "https://mcp.rippit.com/mcp",
  "signup_url": "https://app.rippit.com/signup"
}
```

| Status | `error` | Meaning |
| - | - | - |
| `401` | `unauthorized` | The token is missing, expired or invalid. The `WWW-Authenticate` header points to the sign-in metadata, and MCP clients start sign-in from it on their own. |
| `403` | `forbidden` | The token lacks the `mcp` scope. Create one with `rippit token create --scope mcp`. |
| `503` | `temporarily_unavailable` | Sign-in could not be checked right now. Retry after the `Retry-After` time. |

## Bulk API

Errors return a JSON body with a `detail` field. For most statuses it is a message:

```json theme={null}
{"detail": "Job not found"}
```

For `422` it is a list with one entry per invalid field, where `loc` is the path to the field:

```json theme={null}
{
  "detail": [
    {"loc": ["body", "columns", 0, "column"], "msg": "String should match pattern '^[a-zA-Z_][a-zA-Z0-9_]*$'", "type": "string_pattern_mismatch"}
  ]
}
```

| Status | Meaning | What to do |
| - | - | - |
| `401` | The token is missing, wrong or expired. | Check the `Authorization` header, or create a new token. |
| `403` | The Bulk API isn't enabled for your workspace. | Ask your Rippit contact to turn it on. |
| `404` | The source, dataset or job wasn't found. | Check the id. You can only see your own workspace's sources, datasets and jobs. |
| `409` on `/start` | The file wasn't uploaded yet, or the job was already started. | Upload the file first, and call `/start` only once. |
| `413` | The file is over 128 MB. | Split it into smaller files. |
| `400 EntityTooLarge` from the upload link | The file is over 128 MB. | Split it into smaller files. |
| `422` | The request body is invalid, such as a bad column name or type. | Read `detail` for the field that failed. |
| `429` | You reached a limit. | Wait for the `Retry-After` time. See [Rate limits](https://docs.rippit.com/api-reference/rate-limits.md). |

### Job errors

A request can succeed while the job it started does not. Read the job until `status` is `done` or `failed`:

* A `failed` job has the reason in `error`.
* A `done` job can still have skipped rows. Each one is in `result.rejected` with its 0-based `row` number and the reason, and every other row was written.

Fix the rejected rows and upload them again. See [Idempotency and retries](https://docs.rippit.com/api-reference/idempotency.md) for when re-sending a record updates it, and the [Conversations guide](https://docs.rippit.com/api-reference/connect/bulk/conversations.md) and the [Tables guide](https://docs.rippit.com/api-reference/connect/bulk/tables.md).

## Rippit CLI

A failed command exits with status `2` when the command line itself was rejected, and `1` for every other failure. With `--format json`, stderr holds one object:

```json theme={null}
{"error": {"code": "usage_error", "message": "...", "retryable": false}}
```

When `retryable` is `false`, check the result before running the command again. See [Rippit CLI](https://docs.rippit.com/cli.md) for the codes each command returns.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.