Fix MT4 and MT5 API connection errors step by step

Find which connection is failing

An API integration involves several separate checks: your MetaBridgeAPI login, workspace membership, broker credentials, account connection, API key permissions and access for the selected account. Passing one does not automatically pass the others. Start with the action that failed and its response, then change one thing at a time.

For example, signing into the console proves your app login works. It does not prove a broker password is correct. Likewise, seeing an account in Trading accounts proves the record exists, but it does not mean the broker connection is active. A successful quote in Explore data verifies a console-session request; your integration still needs its own authorized API key.

Check the broker password, platform and server together

If Connect fails after saving an account, compare its details with those supplied by the broker. Use the account’s trading password, not the password used to sign into the broker’s website or MetaBridgeAPI. Select MT4 for an MT4 account and MT5 for an MT5 account. The same broker can run separate servers for each platform and for demo and live accounts.

• Check the complete login number and exact server label, including a demo or live suffix.
• Confirm that those same details can sign into the intended broker account in MetaTrader.
• For advanced setup, check the broker address and port rather than guessing from the website URL.
• Correct a saved account only when it is disconnected and no connection attempt is in progress.

Avoid repeatedly adding the same account to work around a failed connection. A duplicate or concurrent change can return 409. Open the existing record, inspect its status and correct its details there. Account records referenced by saved trading operations have restrictions on broker-identity changes, so use a separate record for a genuinely different broker account.

Understand “active or needs recovery”

This message describes the connection’s lifecycle state. A previous connect or disconnect may still be active, or its result may need recovery before another change is accepted. It does not by itself mean your password is wrong or your broker account has been deleted.

Refresh the account’s state before clicking Connect again. If an operation is still progressing, allow it to finish. If the console continues to report recovery is needed, contact support with the failed request ID and time. Repeated connection attempts or deleting and recreating records can make the sequence harder to diagnose.

Separate authentication, permissions and paid access

For application requests, send Authorization: Bearer followed by the full API key. Use the workspace UUID and account UUID from MetaBridgeAPI in the URL. The broker login number is not either UUID. Check that the key has not expired or been revoked and that it belongs to the intended workspace.

• 401: Check the API key. If the error is in an owner-only console action, check your signed-in session instead.
• 403: Check both the permission and account selection. Quotes need market:read; streams need streams:read. Workspace management actions require an owner session.
• 402: Open Billing and check access for this specific account. Being connected does not activate its trial or include it in a paid plan.
• 409: Inspect account state or the existing operation before trying another change.

The trial covers one broker-confirmed demo account for 14 days from activation, with one trial per owner. A live account requires paid access. A paid plan covers the accounts selected for that purchase. Returning from checkout or creating an invoice is not confirmation of payment; access starts after full payment is confirmed.

Use a small read-only request to isolate the problem

Set METABRIDGE_API_KEY, METABRIDGE_WORKSPACE_ID and METABRIDGE_ACCOUNT_ID in your environment. With an accounts:read key that can access this account, request its summary. This prints the response headers and body so you can distinguish an HTTP error from a successful JSON result.

curl --silent --show-error --include \
  --header "Authorization: Bearer $METABRIDGE_API_KEY" \
  "https://metabridgeapi.com/api/v1/organizations/$METABRIDGE_WORKSPACE_ID/accounts/$METABRIDGE_ACCOUNT_ID/summary"

If the summary works but a quote fails, check the key’s market:read permission and copy the symbol from the broker’s Symbols list. A 400 response can indicate invalid fields or a symbol mismatch. If a stream fails, also check streams:read, active account access and whether another quote stream is already using that broker session. Streams accept up to ten distinct exact symbols.

Retry according to the result

For 429, wait for Retry-After. For 502 or 503, check connectivity and whether the requested feature is available for that platform and account. Avoid a tight retry loop. MT4 and MT5 share many routes but do not expose identical features; the MT4 API, MT5 API and API guide describe those differences.

When contacting support, provide the request ID, UTC time, platform, action and HTTP status, with a short description of what happened immediately before the failure. Keep broker passwords and API keys private. This gives support a specific request to investigate while preserving the credentials your integration uses.