Error envelope

Every Cloven error response, on every surface, follows one shape. Branch on code, surface message to humans, log requestId for support.

{
  "error": {
    "code": "pack_access_denied",
    "message": "your key does not have access to pack 'ai'; upgrade to unlock all packs",
    "requestId": "req_01HXY8AB..."
  }
}

The MCP surface wraps the same payload inside the tool error contract:

{
  "isError": true,
  "content": [
    { "type": "text", "text": "pack_access_denied: your key does not have access to pack 'ai'..." }
  ]
}

The SDK throws a typed ClovenApiError carrying code, message, requestId, and status.

Status codes

Status	Code	Cause	Resolution
400	`missing_query`	`/v1/search` called without `q`	Supply a non-empty `q` param.
400	`missing_at`	`/v1/snapshot` called without `at`	Supply an ISO8601 `at`.
400	`invalid_at`	`at` is not a parseable ISO8601	Use `new Date().toISOString()` or equivalent.
400	`missing_ref`	`/v1/cite` called without `ref`	Supply integer `ref` ≥ 1.
400	`invalid_ref`	`ref` is not a positive integer	Supply integer `ref` ≥ 1.
400	`invalid_payment_header`	`x-402-payment` header malformed	Re-encode the proof; confirm base64 JSON.
400	`wrong_network`	Payment header declares a network other than `robinhood`	Settle on Robinhood Chain (id `4663`) — the Base rail is retired.
400	`wrong_scheme`	Payment header `scheme` is not `x402`	Echo `scheme` back verbatim from the quote.
400	`invalid_tx_hash`	Not a 0x-prefixed 32-byte hex string	Pass the raw tx hash from the receipt.
400	`invalid_payer`	Not a 0x-prefixed 20-byte address	Pass the signing wallet's address.
400	`tx_not_found`	No receipt for that hash on Robinhood Chain	Confirm the tx landed at `robinhoodchain.blockscout.com`; you may be on the wrong chain.
400	`tx_reverted`	Transfer tx reverted on-chain	Check USDG balance and gas (ETH); pay again.
400	`no_stable_transfer_in_tx`	No USDG `Transfer` to the treasury in that receipt	Confirm you transferred USDG to the quoted `recipient`.
400	`tx_too_old`	Tx block timestamp > 10 min ago	Pay a fresh tx.
400	`insufficient_payment`	Summed USDG `Transfer` value below quote	Re-quote, pay the full amount. No partial credit.
401	`invalid_token`	Bearer/SSE token failed validation	Re-issue from `/console`.
401	`missing_token`	SSE called without `token` query param	Add `?token=cv_…`.
401	`key_revoked`	Key was revoked since last cache refresh	Issue a replacement.
402	`payment_required`	No auth + no payment proof	Pay USDG per the x402 spec. Body carries `PaymentRequirements`.
403	`pack_access_denied`	Key tier doesn't include the requested pack	Upgrade tier or change `pack`.
404	`pack_not_found`	Unknown pack id	Check `cloven://packs` or pack catalog.
404	`snapshot_not_found`	No snapshot at the requested minute	Try a nearby minute; older snapshots require Pro+.
404	`citation_not_found`	`ref` out of range for this pack	Check `pack.sources.length`.
429	`quota_exhausted`	Tier quota exceeded	Wait for window roll or upgrade. `Retry-After` header included.
500	`internal_error`	Unhandled — engineering paged	Retry with backoff; report `requestId`.
503	`state_unavailable`	First pulse hasn't landed (cold pack)	Retry in 30s.
503	`brief_unavailable`	Pack hasn't produced first brief	Retry in 60s.

Codes are stable

code values are part of the public contract. They will not change without a major version bump. New codes may be added — branch on known codes, default to "log + retry" for unknown ones.

`requestId`

Every response — success or error — carries X-Request-Id. On errors it's also inlined into the error envelope. Pass it to support and we can pull the full trace (route, pack, source health snapshot, Groq token counts) in one query.

requestId is a ULID — sortable by creation time, safe to log, safe to surface to end users.

Error voice

Cloven error messages are concrete, technical, and never blame the user when the cause is on our side. Read them — they tell you the fix.

Good: "your key does not have access to pack 'ai'; upgrade to unlock all packs".
Good: "no snapshot found for pack 'crypto' at 2026-05-23T03:04 (snapshots older than 24h require a Pro+ subscription and Postgres lookup)".
Bad (we don't do this): "Error occurred. Please try again.".

If you ever see a vague message, file an issue — that's a bug in our error catalog.

Retries

Cloven endpoints are idempotent (the cite endpoint accepts both GET and POST; POST is for symmetry, not state mutation). Safe to retry on 5xx and 429 with exponential backoff. Do not retry on 400/401/403/404 — those errors indicate a request shape problem that retrying won't fix.

x402 retries are special: a 402 means "pay first, then retry". The SDK handles this transparently in wallet mode. If you're rolling your own client, treat 402 as the start of a payment dance, not as a retry condition.

A 400 with an x402 code means the payment proof you presented was rejected — a 400 is Cloven's answer to "you gave me a header and it doesn't verify", while 402 is "you gave me nothing". Retrying the same header will not help. Read the code (wrong_network, tx_not_found, insufficient_payment, …), fix the cause, and pay fresh.

Rate limit detail

The 429 response carries Retry-After: <seconds> indicating when your quota window rolls. The sliding window is per-key. Multiple keys on the same account each have their own window. Plan around the window if you batch — the cleanest pattern is to back off until Retry-After, then resume at half the previous rate.