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

# Idempotency and retries

> Which Rippit operations are safe to repeat, which are not, and how to check the result before repeating a write.

Rippit has no `Idempotency-Key` header. Each operation is either safe to repeat by design, or gives you a way to check what happened before you repeat it.

## What to do after a failure

| Failure | Retry? |
| - | - |
| `429` | Yes, for any operation. The call was rejected before it ran. |
| Timeout or `5xx` on a read | Yes. |
| Timeout or `5xx` on a write | Check first. The write may have taken effect. |
| `400`, `403`, `404`, `422` | No. The same call fails again until its arguments change. |

See [Errors](https://docs.rippit.com/api-reference/errors.md) for what each status means and [Rate limits](https://docs.rippit.com/api-reference/rate-limits.md) for how long to wait after a `429`.

## Bulk API

Uploads are built to be run again, on a schedule or after a failure.

| Operation | Repeating it |
| - | - |
| Create a conversation source or a dataset | Safe. The same `name` returns the existing one with `status: "exists"`. |
| Upload conversations | Safe. A conversation is matched on its source and `conversation_id`, and each message on its `event_id`, so the same file updates what is there. A new `event_id` adds a message. |
| Upload rows to a dataset with a primary key | Safe. A row whose key already exists replaces that row. |
| Upload rows to an append-only dataset | Not safe. There is no key to match on, so the rows are added again. |
| Ask for an upload slot | Makes a new slot each time. Only uploads that complete count toward the [limits](https://docs.rippit.com/api-reference/rate-limits.md). |
| `POST /bulk_ingest/jobs/{job_id}/start` | Safe. A job starts once; a second call returns `409`. |
| `GET /bulk/jobs/{job_id}` | Safe. Reading an export job again returns fresh download links without starting another export. |
| `POST /bulk_export/tables` | Starts a new export each time, and each one counts toward the export limits. |

If `/start` times out, read the job with `GET /bulk/jobs/{job_id}` before sending the file again. See the [Conversations guide](https://docs.rippit.com/api-reference/connect/bulk/conversations.md#updating-conversations) for how to keep `conversation_id` and `event_id` stable across uploads.

## MCP tools

Every tool states whether it is safe to repeat in its MCP annotations, which your client receives in the tool list:

* `readOnlyHint: true` means the tool changes nothing.
* `idempotentHint: true` means calling it again with the same arguments has no further effect.

For the operations in this reference:

| Safe to repeat | Not safe to repeat |
| - | - |
| Every `list_`, `describe_` and `read_` operation | `create_worksheet`: makes another worksheet |
| `aggregate_table`, `pivot_table` | `enrich_worksheet`: starts another enrichment job, which is billed |
| `get_integration_state`, `get_enrich_status` | `export_worksheet`: writes another file |
| `import_integration` | `connect_integration` |
| | `manage_snowflake_connection`, `manage_snowflake_import` |

### Jobs

Tools that start long-running work return a job id right away. Reading a job's status is always safe, and a failed status read does not cancel or restart the job. Read the status again with the same id; do not start the job again.

### Check before repeating a write

When a write times out or returns `5xx`, it may already have taken effect. Look for what the call would have made before calling it again:

* After `create_worksheet`, call `list_worksheets`.
* After `enrich_worksheet`, call `describe_table` on the worksheet and look for the new columns.

### Request ids

`agent_search`, in workspaces where it is turned on, takes a `requestId`. Give each search its own id and reuse that id when you retry: the same `requestId` with the same arguments returns the original search instead of running, and billing, a second one.

## Rippit CLI

With `--format json`, a failed command reports `retryable` in its error. When it is `false`, check the result before running the command again. For example, a worksheet creation that timed out reports `creation_unconfirmed`; list worksheets with `rippit data list --kind worksheet` before creating it again. See [Rippit CLI](https://docs.rippit.com/cli.md).


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