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"]
}