Errors

Every error the API produces has the same shape, and every response, error or not, starts with the environment that answered. This page is the whole error story: the envelope, the codes, what to branch on, and the one deliberate exception.

The envelope

{
  "environment": "sandbox",
  "error": {
    "code": "chain_not_allowed",
    "message": "Human-readable explanation",
    "fields": { "applicantInfo.nationality": "iso3166_1_alpha2" }
  }
}

code is what you branch on. It is stable.
message is for your logs, not your users. Its wording may change.
fields appears only when a bank endpoint refused a specific input, and it names the field, never the value.
environment says which upstreams answered: sandbox or production. Read it off any response you paste into a ticket.

Every endpoint page in the API reference lists the codes that endpoint can answer, per HTTP status.

The codes

HTTP	`code`	What happened	What to do
400	`invalid_request`	A field is missing or malformed, or the body is not valid JSON. The message names the field.	Fix the request. Retrying the same body will not help.
400	`no_route`	No provider can route that pair or currency right now.	A normal, temporary answer. Re-quote later; do not retry in a loop.
400	`quote_expired`	The quote is past its `validUntil`.	Request a fresh quote and build from that one.
401	`unauthorized`	Missing, malformed or unknown API key. We do not say which.	Check the header and the key.
403	`permission_denied`	Valid key, but it does not carry the product this endpoint needs.	Ask us to add the product to your key.
403	`chain_not_allowed`	Valid key, but not enabled for that chain on that side.	Ask us to enable the corridor. Retrying will not help.
403	`token_not_allowed`	Valid key, but not enabled for that token on that chain.	As above.
403	`execution_capped`	The transfer exceeds the key’s execution ceiling in USD. The key’s policy, not liquidity.	Quote a smaller amount, or ask us to raise the ceiling.
403	`quote_not_verified`	The quote does not verify, or was issued to a different key.	Build only from a quote this key received.
404	`not_found`	No such endpoint, or no such thing behind the id.	Check the path and the id.
404	`order_not_found`	Unknown or malformed order id, or an order another key built.	Ask with the id the create call returned.
409	`transaction_conflict`	This order already follows another transaction hash.	Report each order once.
429	`rate_limited`	Over your key’s requests per second.	Back off, then retry.
500	`internal`	Unexpected server error. Details are never leaked.	Retry with backoff; tell us if it persists.
501	`not_implemented`	This deployment cannot answer that call, for instance reading a virtual account back where `readBack` is false.	Keep the details the create call returned.
502	`upstream_error`	A provider behind the rail is unavailable or answered badly.	Retry with backoff.
503	`not_configured`	This deployment has no provider configured for that product.	Contact us.

The bank onboarding flow adds a few of its own on the consent calls: consent_session_invalid, consent_declined, consent_link_failed and, on the sandbox identity call, kyc_provider_refused. Each is listed on the endpoint page that answers it.

What to branch on

Branch on code and the HTTP status. Never on message: its wording is not part of the contract.
Three are worth handling on their own. no_route is temporary: re-quote later. rate_limited means back off, not retry at once. chain_not_allowed means the corridor was never yours, so no retry will fix it.
A 4xx on a create call created nothing. There is no order or payout to clean up; fix the request and call again.
Do not enumerate the codes for the user. Show your own copy per branch and keep code and message in your logs for the support ticket.

The exception: bank transfers and virtual accounts

On the bank transfer and virtual account endpoints the envelope is the same, but code and fields inside it are the banking partner’s own, passed through unchanged rather than mapped to the table above. The set is theirs and it can grow, so there:

branch on the HTTP status first,
log code as a string rather than matching it against a fixed set,
read fields to know which input to fix; it names the field, not the value.

{
  "environment": "sandbox",
  "error": {
    "code": "<the banking partner's code>",
    "message": "Human-readable detail from the banking partner",
    "fields": { "applicantInfo.nationality": "iso3166_1_alpha2" }
  }
}

The flows this applies to are on On-ramp and Virtual accounts.

Which products, chains and tokens your key carries, and why a request is refused rather than defaulted: Authentication.
Rate limits and what your key’s ceiling means for your own users: Rheon API.

Getting started

Concepts

Products

Integration

Pricing

Webhooks

The envelope

The codes

What to branch on

The exception: bank transfers and virtual accounts

​The envelope

​The codes

​What to branch on

​The exception: bank transfers and virtual accounts

​Related

The envelope

The codes

What to branch on

The exception: bank transfers and virtual accounts

Related