Error catalogue

Every code the gateway answers, its HTTP status, what it means and what to do

Every error has one envelope
Branch on code, never on message: the sentence may be reworded, the code will not
docs links the code's row on this page, and details carries the numbers behind a refusal
The words are the gateway's own catalogue (packages/api/errors.mjs), and the same list is the Refusal enum in the OpenAPI file; a check in each repository fails when the gateway throws a code that is missing here

{
  "error": {
    "code": "RISK_MAX_LOTS",
    "message": "Requested volume exceeds the account's maximum lots per order.",
    "docs": "https://mirroapi.com/docs/errors#RISK_MAX_LOTS",
    "details": { "arithmetic": { "requestedLots": "9.00", "maxLots": "2.00" } }
  }
}

The envelope

Answered by every route

The sandbox boundary

A test key (mk_test_…) stays on demo accounts; these are the two places it meets live money

Platforms and provisioning

GET /platforms, POST /accounts and the configuration links
selfOnboard.reason on a platform row is the same code POST /accounts answers

Trading and risk

Answered by POST /accounts/{id}/trades and PUT /risk before a command is queued
Nothing was sent unless the row says otherwise; a refusal is also written to the audit log as order.refused

Command results

Not HTTP errors: these arrive in Command.result.code on GET /accounts/{id}/trades/{commandId} (and in the command.resolved webhook)
EXECUTION_UNKNOWN arrives there too, meaning a terminal took the command and never answered: the outcome is not known and it is never called rejected

Execution diagnostics

A broker refusal has a code, a readable reason and its original terminal details
An unknown execution outcome stays unknown until evidence resolves it
Alongside result.code above, a resolved command carries result.diagnostic: the specific code, what it means and what to do next
The established result.code is unchanged, and REST, streams and command.resolved webhooks use the same diagnostic shape

{
  "state": "rejected",
  "result": {
    "code": "BROKER_REJECTED",
    "native": { "code": 10016, "message": "Invalid stops" },
    "diagnostic": {
      "code": "MT5_INVALID_STOPS",
      "known": true,
      "source": "mt5",
      "reason": "A stop or pending price violates the broker’s price or distance rules.",
      "outcome": "rejected"
    }
  }
}

This is an abbreviated example
The diagnostic also includes the original response, catalogue version, retry guidance and a next step
The console shows the specific code and reason on the order, beside the words above

Discover the codes

curl --fail-with-body \
  -H "Authorization: Bearer $MIRRO_API_KEY" \
  https://api.mirroapi.cloud/v1/error-codes

The versioned catalogue covers published MetaTrader 4 and MetaTrader 5 trade return codes and MIRRO execution preflight reasons
Future, runtime and vendor-specific codes can be unclassified: known: false keeps the original value and message rather than inventing an explanation
HTTP refusals also include error.code, error.message, optional details and an X-Request-Id support reference

Handle uncertainty without duplicating trades

EXECUTION_UNKNOWN means the trade may have executed
A native timeout or connection failure can produce this state immediately
Automatic dispatch stops for that command
Keep its command id and original idempotency key, inspect the account’s orders, positions and deals, and wait for a definitive result or escalate with that id
A later definitive acknowledgement can correct the command
Never treat a missing response as permission to submit the same trade under a new identity

Use the rules of the connected account

• Read the account’s symbol catalogue and preserve exact spelling, case and broker suffixes
• Read symbol specifications before choosing lot size
  MT4 1.9.7 and MT5 1.9.5 reject API sizes outside the minimum, maximum or step; they do not silently resize an explicit trade
• Honour trading sessions, margin, allowed order types, stop and freeze distances, account permissions, hedging and FIFO restrictions
  These rules can change at the broker
• MT5 filling selection accounts for execution mode and symbol flags
  Pending orders request RETURN
  Unsupported rules produce a diagnostic instead of a guessed policy
• Native details require the updated EA
  Older errors carrying a recognised numeric code can still receive a readable explanation; missing measurements or messages are never fabricated

MetaTrader 4 and MetaTrader 5 support does not certify every broker or every account type
Brokers control acceptance, prices, sessions and connectivity
MIRRO cannot override those decisions or guarantee zero failures
Native code references: MetaQuotes MT4 and MetaQuotes MT5

Reads: the book, history and the terminal

A read that could not be made is answered as such, never as an empty book, empty history or an invented price

Copies

POST and PATCH /copies; the copy engine's own words are named codes with the raw reason in details.reason

Billing and card payments

A failed payment-status read does not prove a payment failed
Check its saved reference before retrying and keep the same request id

Console sign-in

Answered to the console's session routes, not to API keys

MAX copy trading

A console product: a provider's master copied into the accounts of the people they invite
Its routes are console routes, not in the OpenAPI file; the codes are listed so the catalogue is complete