> ## Documentation Index
> Fetch the complete documentation index at: https://docs.etherfuse.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Errors

> The problem details format v2 errors use, every problem type you can receive, and the error format of the other endpoints.

Every error from a v2 endpoint returns an [RFC 9457](https://www.rfc-editor.org/rfc/rfc9457) problem details body with content type `application/problem+json`. This includes authentication failures, unsupported methods and malformed JSON. A path that matches no endpoint is the one exception: it returns a plain `404` with an empty body.

The `/lookup` and `/auth` endpoints use a different format. See [Other endpoints](#other-endpoints).

```json theme={null}
{
  "type": "https://docs.etherfuse.com/ramp/v2/errors/quote-expired",
  "title": "Quote expired",
  "status": 400,
  "detail": "quote 5e6f7a8b-9c0d-4e1f-8a2b-3c4d5e6f7a8b has expired or does not exist",
  "instance": "tag:etherfuse.com,2026-08-28:R2-10120/0b1c2d3e-4f50-4a6b-8c7d-9e0f1a2b3c4d"
}
```

| Field | Meaning |
| - | - |
| `type` | `https://docs.etherfuse.com/ramp/v2/errors/` followed by the problem slug. **Use this value to select your error handler.** The URL opens this page. |
| `title` | Short summary of the problem type. The same for every occurrence of a type. |
| `status` | The HTTP status code. |
| `detail` | Human-readable explanation of this occurrence. Show it or log it; do not parse it. For `internal-error` it is always `An unexpected internal error occurred.` |
| `instance` | A unique identifier for this occurrence. Every error gets a new one. Include the full value when you contact support, so we can find the exact request. |

## Extra fields

Two problem types add fields.

**`validation-error`** adds `errors`, one entry per invalid field. `pointer` is a JSON Pointer into your request.

```json theme={null}
{
  "type": "https://docs.etherfuse.com/ramp/v2/errors/validation-error",
  "title": "Your request is not valid.",
  "status": 400,
  "detail": "invalid account details for clabe",
  "instance": "tag:etherfuse.com,2026-08-28:R2-10006/6a7b8c9d-0e1f-4a2b-8c3d-4e5f6a7b8c9d",
  "errors": [
    { "pointer": "#/accountDetails/clabe", "detail": "This field is required." },
    { "pointer": "#/accountDetails/memo", "detail": "This field is not allowed for this account kind." }
  ]
}
```

**`registration-info-required`** adds `required` and `missing`. Both are lists of JSON Pointers into your request: `required` is every registration field the route needs, and `missing` is the ones you still have to send.

```json theme={null}
{
  "type": "https://docs.etherfuse.com/ramp/v2/errors/registration-info-required",
  "title": "Registration information required",
  "status": 422,
  "detail": "required registration information was not supplied",
  "instance": "tag:etherfuse.com,2026-08-28:R2-10022/0b1c2d3e-4f50-4a6b-8c7d-9e0f1a2b3c4d",
  "required": ["#/registrationInfo/accountHolderName", "#/registrationInfo/taxId"],
  "missing": ["#/registrationInfo/taxId"]
}
```

## Problem types

Each heading below is the slug at the end of `type`.

### invalid-request

`400` Invalid request. The request is malformed: bad JSON, an unknown enum value, a bad path or query parameter, or a value that fails a check (for example a CLABE check digit, a non-positive amount, or a `pageSize` outside 1 to 100). Fix the request. `detail` names the problem.

### validation-error

`400` Your request is not valid. One or more fields are missing, not allowed, or malformed. Fix each field listed in `errors`.

### quote-expired

`400` Quote expired. The quote passed to `POST /organization/{organizationId}/order` has expired or does not exist. Create a new quote and use its `quoteId`.

### amount-out-of-range

`400` Amount out of range. The amount is below the minimum or above the maximum of a rail. Change the amount. The account's `rails` show `minAmount` and `maxAmount` when a limit is known.

### sandbox-limit-exceeded

`400` Sandbox limit exceeded. The amount exceeds the sandbox limit for onramps (500 MXN per quote). Use a smaller amount in sandbox. See the [Sandbox Reference](/v2/test-environment).

### unauthorized

`401` Unauthorized. The `Authorization` header is missing, not ASCII, or does not hold a valid API key. Send the raw API key with no `Bearer` prefix, for the right environment. See [Authentication](/v2/authentication).

### forbidden

`403` Forbidden. The request is not allowed here, for example the sandbox simulator called in production, member endpoints called for your own organization, or partner statements read with a customer organization's key. Do not retry.

### not-found

`404` Not found. The resource does not exist or does not belong to the organization in the route, or the `organizationId` in the route is an organization your API key cannot act for. A path that matches no endpoint also returns `404`, with an empty body. Your key can act for its own organization and its direct customer organizations. Check the ids and the path.

### method-not-allowed

`405` Method not allowed. The route exists but not for this HTTP method. The `Allow` header lists the methods it accepts. Use a method from `Allow`.

### conflict

`409` Conflict. The request collides with existing state: a webhook subscription for this URL and event already exists, an order for this quote was created at the same time, the account is registered in a different market, an organization `id` is already in use, or a customer's verification is not at a stage that accepts this write. `detail` says which. Read the existing resource instead of creating it again. See [Idempotency](/v2/idempotency).

### organization-not-approved

`409` Organization not approved. The organization in the route is not approved, so it cannot quote. Complete verification, then quote again.

### payment-account-unavailable

`409` Payment account unavailable. Another organization holds this account. Register a different account.

### payment-account-disabled

`409` Payment account disabled. The account is disabled. It cannot be registered or quoted. Use a different account.

### payment-account-not-ready

`409` Payment account not ready. The account is not `ready` in the needed direction on the chosen rail, is not registered on the rail you named, or has no rail that can carry that direction. Check the account's `rails`. Wait for the direction to become `ready`, or name a rail the account is ready on.

### order-not-cancelable

`409` Order not cancelable. The order can no longer be canceled, for example it already finished. Read the order to see its status.

### order-not-claimable

`409` Order not claimable. The order is not `claimable`, so there is nothing to claim. Read the order to see its status.

### authorization-expired

`409` Authorization expired. The `id` you sent is not the order's current authorization, or it expired. Read the order, sign the new `authorization.method.message`, and send the new `id`.

### authorization-not-required

`409` Authorization not required. The order has no pending authorization. Read the order to see its current state.

### invalid-signature

`400` Invalid signature. The signature is not valid hex, or it does not verify over the authorization's `message` with the embedded wallet's `signerPublicKey`. Sign the exact UTF-8 bytes of `message` with ECDSA P-256 and SHA-256, and send it as DER or `r||s` hex.

### payload-too-large

`413` Payload too large. The request body is too large. Send a smaller body.

### rate-limit-exceeded

`429` Rate limit exceeded. You sent too many requests, for example balance reads for one organization. Wait the number of seconds in the `Retry-After` header, then send the request again.

### quote-unavailable

`422` Quote unavailable. We cannot price this route right now. Retry later with backoff.

### registration-info-required

`422` Registration information required. The route requires registration fields we do not hold and you did not send. Send the fields listed in `missing` under `registrationInfo`.

### holder-tax-id-mismatch

`422` Account holder tax ID mismatch. `registrationInfo.taxId` does not match the verified tax ID. Send the verified tax ID, or leave `taxId` out and we use the verified one.

### unsupported

`422` Unsupported. The operation is not supported, for example a `debitCard` account, an identifier no route accepts, a route we cannot quote, or a sandbox deposit simulation on an order whose source does not receive fiat. Do not retry the same request. Change the account or route.

### internal-error

`500` Internal server error. An unexpected error on our side. Retry with backoff. If it persists, contact support with the `instance`.

### not-implemented

`501` Not implemented. The endpoint is documented but not available yet in this environment. Do not retry. Check the [changelog](/changelog) for when it ships.

### service-unavailable

`503` Service unavailable. A dependency is temporarily unavailable. Retry with backoff.

## Handling errors

* Handle errors by `type`. Use `status` as a fallback for unknown types.
* `4xx` other than `quote-unavailable` and `rate-limit-exceeded`: fix the request before retrying. The same request fails the same way.
* `rate-limit-exceeded`: retry after `Retry-After`.
* `quote-unavailable`, `internal-error` and `service-unavailable`: retry with exponential backoff. `POST /organization/{organizationId}/order` is safe to retry with the same `quoteId`; it returns the existing order instead of creating a second one.
* Keep the `instance` of any error you report to support.

## Other endpoints

The `/lookup` and `/auth` endpoints do not return problem details. `/lookup` returns an HTTP status code with a short message, as plain text or as a JSON object `{ "error": "<message>" }`. `/auth/token` returns OAuth 2.0 errors; see [Authentication errors](/v2/guides/authentication-errors). Handle these by HTTP status code, and display or log the message rather than using it as an error code.

The KYC verification endpoints list every missing or invalid field in one `400` `detail`. Fill them in and send the request again; the call is safe to repeat. See [KYC API error handling](/v2/guides/kyc-api#error-handling).

Still stuck? [Book a session with the team](https://cal.com/team/etherfuse/api-overview?overlayCalendar=true).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.