# Errors and limits

What a refusal looks like, the status codes, rate limits, retries and repeat-safe writes.

## What a refusal looks like

A refusal is JSON with `error` and, in most cases, `message` in plain words. A validation error also lists `details.issues`, each with the path of the field and what is wrong with it.

## Status codes

- `400`: The request is malformed or a value is not allowed. Fix the request before sending it again.
- `401`: No valid credential. The key is missing, wrong, expired or revoked.
- `403`: The credential lacks the scope, or is used from an origin or address it is not allowed on, or the action is kept for a person.
- `404`: No such record in this project. A record in another project also answers 404.
- `409`: The request conflicts with the current state of the record.
- `429`: Too many requests. Wait the number of seconds in the answer and send it again.
- `5xx`: Something failed on our side. A read can be sent again; send a write again only with the same Idempotency-Key.

## Rate limits

Each key has a requests-per-minute limit, set by the plan or lower when the key is made. Past it the answer is 429 with a `Retry-After` header and `retry_after_seconds` in the body. Several processes sharing one key share its limit, so keep parallel work on one key small.

Response:

```
HTTP/1.1 429
retry-after: 12

{
  "error": "rate limit exceeded",
  "code": "rate_limited",
  "limit_class": "…",
  "retry_after_seconds": 12,
  "message": "…"
}
```

## Repeat-safe writes

Send an `Idempotency-Key` header with a write, with a value of your own such as an order number. If the same request arrives twice with the same key, for example after a timeout, it is carried out once. Through MCP the same value is the `idempotencyKey` argument.

Header:

```
Idempotency-Key: order-10482
```

## Versions

An unknown `Rivier-Version` answers 400 with the error `unsupported_version` and the versions the API supports.

Response:

```
{
  "error": "unsupported_version",
  "message": "…",
  "supported": ["2026-11-01"]
}
```