Errors

Every error response carries the same envelope:

{
  "code": "AMOUNT_TOO_LOW",
  "message": "Amount is below the minimum for every eligible route.",
  "requestId": "req_01j6y9d4x2m8",
  "timestamp": "2026-09-02T10:14:52Z",
  "errors": [
    { "field": "amount", "message": "minimum for USDT on TRX via dce is 10" }
  ]
}

code is the stable identifier — branch on it.
message is for humans and may be reworded without notice. Never match on it.
requestId is what to quote when you contact support.
errors[] appears on validation failures, one entry per field.
gatewayDetails appears when a gateway produced the failure: {gateway, code, message} with the gateway's own values.
transaction appears on GATEWAY_ERROR — the reference of the transaction that was created and declined.

New codes can appear as gateways and features are added. Treat an unrecognised code by its HTTP status class.

Codes

Code	HTTP	Meaning	What to do
`UNAUTHORIZED`	401	Key missing, malformed, revoked, or sent to the wrong environment host.	Check the `Authorization` header and that an `omi_test_` key is hitting the sandbox host.
`FORBIDDEN_SCOPE`	403	The key lacks the scope for this endpoint.	Use a key with the right scope; see Authentication.
`OPERATOR_PAUSED`	403	Your operator account is paused. Reads still work.	`message` has the reason. Contact OmiCloud.
`VALIDATION_FAILED`	400	A field is malformed or missing.	Read `errors[]`.
`AMOUNT_TOO_LOW`	400	Below the minimum of every eligible route.	`errors[0]` names the tightest limit. Raise the amount or check `GET /v1/routes`.
`AMOUNT_TOO_HIGH`	400	Above the maximum of every eligible route.	Lower the amount or split it.
`ROUTE_NOT_SUPPORTED`	400	No connected gateway serves this direction / currency / network / method.	Check `GET /v1/routes`. If you expected a route, contact OmiCloud.
`GATEWAY_NOT_CONNECTED`	403	You named a `gateway` your account is not connected to.	Omit `gateway` to let OmiCloud route, or use one from `GET /v1/gateways`.
`GATEWAY_NOT_ENABLED_FOR_DIRECTION`	400	The named gateway does not do this direction (e.g. payouts).	Omit `gateway` or choose another.
`IDEMPOTENCY_KEY_REUSED`	409	Same `Idempotency-Key`, different body, within 24 h.	Use a new key for a new intent. See Idempotency.
`NOT_FOUND`	404	No such transaction / session / endpoint on your account.	Check the id. Other operators' ids also return this — nothing is revealed.
`QUOTE_TIMEOUT`	408	No gateway answered a quote in time.	Retry with backoff. Not a failure of your request.
`GATEWAY_ERROR`	502	The gateway failed or was unreachable during submission. The transaction was created and declined.	Read `gatewayDetails`. Do not retry with the same idempotency key — send a new request.
`GATEWAY_AUTH_ERROR`	502	OmiCloud's credentials with the gateway were rejected. Your key is not at fault.	OmiCloud is alerted automatically. Retry later or route to another gateway.
`RATE_LIMITED`	429	Too many requests for this key.	Honour `Retry-After`.
`INTERNAL`	500	Something failed on OmiCloud's side.	Retry with backoff. If it persists, contact support with `requestId`.

Which errors are safe to retry

Retry as-is	Retry with a new request	Do not retry
`QUOTE_TIMEOUT`, `RATE_LIMITED`, `INTERNAL`, `GATEWAY_AUTH_ERROR`, network errors	`GATEWAY_ERROR` (a transaction already exists)	every `4xx` except `408`/`429` — the answer will not change

HTTP status by class

Class	Meaning
`2xx`	Done. `201` on creates, `200` on reads and updates, `204` on deletes.
`4xx`	Your request. Fix it before retrying (except `408`, `429`).
`5xx`	OmiCloud or a gateway. Retry with backoff; `502` means a gateway.