> ## 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 > HTTP status codes the Etherfuse API returns, what causes them, and how to handle them. The API uses conventional HTTP status codes. A `2xx` means success; a `4xx` means the request was rejected (usually something you can fix); a `5xx` means a problem on Etherfuse's side. Error responses carry a **short, human-readable message** describing the problem — for example, `An order with this transaction ID already exists`. Depending on the endpoint, the body is either plain text or a JSON object `{ "error": "" }`. Switch on the **HTTP status code** as the primary signal and treat the message as human-facing detail — there is no stable machine-readable error code to parse. ## Status codes | Code | Meaning | Typical cause | | ----- | --------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | | `400` | Bad Request | Invalid or missing fields, or a missing/expired quote. | | `401` | Unauthorized | Missing/invalid API key, or a `Bearer` prefix on the header. See [Authentication](/authentication). | | `403` | Forbidden | Your organization isn't authorized to access this resource. | | `404` | Not Found | A referenced ID doesn't exist or isn't linked to the customer/org (wrong `customerId`, `bankAccountId`, `publicKey`, etc.). | | `409` | Conflict | The resource already exists, or it collides with a business rule. See [Idempotency](/idempotency). | | `422` | Unprocessable Entity | The request is well-formed but can't be processed — e.g. an unsupported asset, currency, or blockchain for the requested operation. | | `424` | Failed Dependency | A valid quote couldn't be produced for the requested trading path right now (a `FailedToGetQuote`). Transient — retry with backoff. | | `500` | Internal Server Error | Unexpected error on our side. Safe to retry with backoff. | | `501` | Not Implemented | The requested capability isn't available for this route (e.g. an unsupported provider or flow). | | `503` | Service Unavailable | A dependency is temporarily down. Retry with backoff. | ## Common errors | Message / situation | Code | Cause | Fix | | ------------------------------------------------------------------------------------ | ----- | --------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | | `Proxy account not found` | `404` | `customerId` or `publicKey` doesn't match onboarding | Use the exact IDs from the onboarding call. | | `Bank account not found` | `404` | `bankAccountId` is wrong or belongs to a different customer | Verify the bank account is linked to this customer. | | Quote expired | `400` | Order created more than **2 minutes** after the quote | Create a fresh quote and retry. | | `An order with this transaction ID already exists` | `409` | Re-used an `orderId` | See [Idempotency](/idempotency) — treat as already-created. | | `A pending onramp order already exists for this bank account and amount` | `409` | Duplicate pending onramp for the same `(bank account, amount)` | Wait for the existing order to settle, or change the amount. | | `401 Unauthorized` | `401` | `Bearer` prefix or wrong-environment key | Send the raw key matching the base URL. | | `FailedToGetQuote` — "Temporarily unable to get a valid quote for this trading path" | `424` | Etherfuse can't currently guarantee the fee/spread for that trading path | Transient protection — retry with exponential backoff. | | `OrderTooSmall` — "Combined fee … exceeds maximum (5000 bps / 50%)" | `400` | Amount too small to cover fees (EVM offramp gas, or a new-wallet Stellar onboarding cost) — the fee can't exceed 50% of the order | Increase the amount (on EVM, offramp ≳ 50 CETES). See [Base](/guides/chains/base). | | `tx_too_late` (returned by Stellar on submit) | — | The pre-built Stellar transaction expired (\~1–2 min TTL) before you submitted it | Regenerate with [`regenerate_tx`](/api-reference/orders/regenerate-tx) and resubmit promptly. See [Stellar](/guides/chains/stellar). | **IDs are permanently bound after onboarding.** The `customerId`, `bankAccountId`, and `publicKey` are linked during onboarding and cannot be mixed across customers — mismatches surface as `404`. ## Handling errors * **`4xx`** — fix the request before retrying. Retrying an identical bad request will fail the same way. For `409` on a create, treat the resource as already created (see [Idempotency](/idempotency)). * **`424`** — a quote couldn't be produced for that trading path right now (a price/spread couldn't be guaranteed). It's transient — retry with exponential backoff. * **`5xx`** — `500` and `503` are transient; retry with exponential backoff. Because creates use [client-generated UUIDs](/idempotency), a retry won't create a duplicate. `501 Not Implemented` is **not** retryable — the operation isn't supported, so adjust the request instead. * **Quotes** expire after 2 minutes — refresh the quote rather than retrying the order. * **Expired Stellar transactions** (`tx_too_late`) — don't resubmit the same XDR; regenerate it (see [Stellar](/guides/chains/stellar#transaction-expiry-and-regeneration)) and submit the fresh one. Still stuck? [Book a session with the team](https://cal.com/team/etherfuse/api-overview?overlayCalendar=true).