Documentation

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