Skip to main content
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": "<message>" }. 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

Common errors

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).
  • 424: a quote couldn’t be produced for that trading path right now (no liquidity was available, or a price/spread couldn’t be guaranteed). It’s transient; retry with exponential backoff. Distinguish this from a 404 NoPathsFound, which means no market exists for the pair at all and won’t succeed on retry.
  • 5xx — 500 and 503 are transient; retry with exponential backoff. Because creates use client-generated UUIDs, 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) and submit the fresh one.
  • Reporting a problem: responses carry an X-Trace-Id header (32 hex characters), and v2 error bodies repeat it as traceId. Send it to us with the time of the request, and we can find that request.
Still stuck? Book a session with the team.