GaiaExGaiaEx
API

GaiaEx API Error Codes: Causes & Fixes

Resolve GaiaEx API errors fast. Full reference: every HTTP error code, root cause, and exact fix for auth, rate limits, orders, and positions.

AI AGENT READYEquip Claude Code, OpenAI Codex & Antigravity (`agy`) with Official GaiaEx Skills
CLAUDE CODESKILL.md
Claude SKILL.md

Drop-in Claude Code skill with HMAC-SHA256 signing, /fapi/v1 & /fapi/v2 schemas, and secret-redaction guardrails.

Raw ↗
OPENAI CODEXAGENTS.md
Codex AGENTS.md

Drop-in repository AGENTS.md for OpenAI Codex CLI — tick-size rules, rate-limit budgets, and self-custody boundaries.

Raw ↗
ANTIGRAVITYAGY.md
Antigravity AGY.md

Google Antigravity (agy) & Gemini agent spec with verified async Python WebSocket + REST execution templates.

Raw ↗
UNIVERSAL LLMllms.txt
/llms.txt Index

Single-URL machine-readable index of all GaiaEx documentation pages, OpenAPI 3.0 schema, and Postman collection.

Raw ↗

HTTP Status Codes

GaiaEx uses standard HTTP status codes alongside GaiaEx Unified Futures error payloads ({"code": -1121, "msg": "Invalid symbol."}) across all /fapi/v1/* and /fapi/v2/* endpoints.

HTTP CodeMeaningDescription & Action
200OKRequest succeeded and payload matches the GaiaEx Unified Futures schema.
400Bad RequestMalformed parameters, invalid symbol, precision mismatch, or rejected order/cancel. Inspect the JSON code and msg fields.
401UnauthorizedMissing or invalid X-MBX-APIKEY header, expired timestamp, or invalid signature.
403ForbiddenWAF/IP restriction triggered, or the API key lacks the required permission (read / trade).
429Too Many RequestsRequest weight rate limit exceeded. Back off immediately and respect the Retry-After header.
500Internal Server ErrorUnexpected server-side error. Treat order execution state as UNKNOWN and reconcile via GET /fapi/v1/openOrders or GET /fapi/v1/order.
503Service UnavailableUpstream matching engine temporarily unavailable or overloaded. Wait and query order status before retrying.

Standard Error Payload

{
  "code": -1022,
  "msg": "Signature for this request is not valid."
}

10xx — General, Server & Authentication Errors

Error CodeNameHTTPCauseSolution
-1000UNKNOWN500An unknown error occurred while processing the request.Check GET /fapi/v1/openOrders before retrying any state-changing order request.
-1001DISCONNECTED503Internal error; unable to process your request.Retry after a brief backoff; verify open orders via GET /fapi/v1/openOrders.
-1002UNAUTHORIZED401You are not authorized to execute this request (missing X-MBX-APIKEY or insufficient scope).Pass a valid X-MBX-APIKEY header with read / trade permissions enabled.
-1003TOO_MANY_REQUESTS429Too many requests queued or request weight exceeded.Respect Retry-After and switch polling workflows to WebSocket streams.
-1021INVALID_TIMESTAMP400 / 401Timestamp for this request is outside of the recvWindow (default 5000ms).Sync clock via GET /fapi/v1/time and pass millisecond timestamp.
-1022INVALID_SIGNATURE400 / 401Signature for this request is not valid.Compute HMAC-SHA256 over the exact query string or form body (excluding &signature=...).

11xx — Request Parameter & Filter Errors

Error CodeNameHTTPCauseSolution
-1100ILLEGAL_CHARS400Illegal characters found in a parameter.URL-encode parameters and ensure numeric strings contain only digits and decimal points.
-1102MANDATORY_PARAM_EMPTY_OR_MALFORMED400A mandatory parameter was not sent, was empty/null, or malformed.Verify required parameters (e.g. symbol, side, type, timestamp, signature).
-1111BAD_PRECISION400Precision is over the maximum defined for this asset.Round price to tickSize and quantity to stepSize from GET /fapi/v1/exchangeInfo.
-1121BAD_SYMBOL400Invalid symbol.Use a valid symbol (e.g. BTCUSDC, ETHUSDC, BTCUSDT) listed in GET /fapi/v1/exchangeInfo.

20xx & 40xx — Order, API Key & Margin Errors

Error CodeNameHTTPCauseSolution
-2010NEW_ORDER_REJECTED400New order rejected by the matching engine (e.g. post-only would cross, min notional < $10, or price outside band).Inspect msg for the specific filter or margin rejection reason.
-2011CANCEL_REJECTED400Cancel rejected because the order was never placed, already canceled, or already filled.Reconcile active orders via GET /fapi/v1/openOrders. Note that PUT /fapi/v1/order replaces the orderId.
-2013NO_SUCH_ORDER400 / 404Order does not exist.Check orderId or origClientOrderId via GET /fapi/v1/allOrders.
-2014BAD_API_KEY_FMT401API-key format invalid.Verify the X-MBX-APIKEY header contains the full GaiaEx API key string.
-2015REJECTED_MBX_KEY401 / 403Invalid API-key, IP not in whitelist, or permissions insufficient for action.Verify key status, IP whitelist, and trade scope in the GaiaEx mobile app.
-2019MARGIN_NOT_SUFFICIENCE400Margin is insufficient to place the order.Check available margin via GET /fapi/v2/balance, or reduce quantity / adjust leverage via POST /fapi/v1/leverage.
-4003QTY_LESS_THAN_ZERO400Quantity less than or equal to zero.Pass a positive decimal quantity meeting the symbol's LOT_SIZE filter.
-4028LEVERAGE_NOT_WITHIN_LIMIT400Leverage is not within the symbol's allowed bracket.Query GET /fapi/v1/leverageBracket or GET /fapi/v1/exchangeInfo for maximum allowed leverage.

Error Handling Best Practices

import hmac, hashlib, time, urllib.parse, requests

BASE = "https://openapi.gaiaex.com"
API_KEY = "gx_live_..."
API_SECRET = "gx_secret_..."

params = {
    "symbol": "ETHUSDC",
    "side": "BUY",
    "type": "LIMIT",
    "timeInForce": "GTC",
    "quantity": "0.1",
    "price": "3500.00",
    "timestamp": int(time.time() * 1000),
}
query = urllib.parse.urlencode(params)
sig = hmac.new(API_SECRET.encode(), query.encode(), hashlib.sha256).hexdigest()

resp = requests.post(
    f"{BASE}/fapi/v1/order?{query}&signature={sig}",
    headers={"X-MBX-APIKEY": API_KEY},
)
if resp.status_code != 200:
    err = resp.json()
    print(f"HTTP {resp.status_code} | code={err.get('code')} msg={err.get('msg')}")
  1. Inspect both HTTP status and code / msg — every /fapi/v1/* and /fapi/v2/* error returns a structured JSON object with a negative integer code and descriptive msg.
  2. Validate precision before sending — cache GET /fapi/v1/exchangeInfo at startup to validate PRICE_FILTER (tickSize), LOT_SIZE (stepSize), and MIN_NOTIONAL client-side.
  3. Handle 429 TOO_MANY_REQUESTS (-1003) gracefully — respect the Retry-After header and use exponential backoff.
  4. Track updated orderId after PUT /fapi/v1/order — modifying an order atomically cancels and replaces it under a new orderId.
  5. Sync clocks for -1021 INVALID_TIMESTAMP — verify local NTP sync against GET /fapi/v1/time so your millisecond timestamp stays within recvWindow.