# Troubleshooting

> Use this page when API reads do not match what you expect. Most issues fall into one of four buckets: invalid request parameters, stale snapshots, using the wrong surface for the job, or expecting immediate read-after-write consistency.

# Troubleshooting

Use this page when API reads do not match what you expect. Most issues fall into one of four buckets: invalid request parameters, stale snapshots, using the wrong surface for the job, or expecting immediate read-after-write consistency.

## `400 Bad Request`

Both read endpoints and order preparation return `400` for requests that can't be accepted.

Common read cases:

- `/orders` and `/positions` require a valid account address.
- `/markets/tickers` validates `addresses` and `symbols` filters.
- `/markets/trading-capacity` requires a valid `symbol` and a `direction` of `long` or `short`.
- `/rates` validates `period` and `averageBy`.
- `/apy`, `/yield/gm-pools`, and `/performance/*` validate their filters. `/yield/gm-pools` rejects malformed pool addresses.
- `/yield/gm-user-earnings` requires a valid `account` address.
- `/trades` `since` and `until`, and `/trades/search` `fromTimestamp` and `toTimestamp`, must be whole Unix seconds from `0` to `2147483647`. A fractional or millisecond value returns `Invalid since timestamp: whole seconds expected` (with the field's name).
- `/stats/*` rejects an unknown `networks`, `versions`, or `metric` value, and a `from` or `to` that isn't whole Unix seconds. Repeat a list parameter for each value (`networks=arbitrum&networks=avalanche`); a comma-separated list is rejected. A filter that matches no configured source, such as `networks=megaeth&versions=v1`, returns `No configured source matches the requested networks and versions`.

For schema validation failures, such as a missing required parameter or a value outside an enum, the `message` field is an object keyed by parameter name instead of a string.

`POST /orders/txns/prepare` can also return an application error:

- `INSUFFICIENT_LIQUIDITY` means a Market Increase exceeds current JIT-aware trading capacity. Reduce the requested size or refresh capacity before preparing again. A resting increase can return the same code in `validationWarnings` instead because liquidity will be checked again when it triggers.
- `INSUFFICIENT_COLLATERAL` means collateral remaining after fees would be below the on-chain minimum. Add collateral or change the order. For TWAP increases, every part must satisfy the minimum.

`validationWarnings` are non-blocking, but clients need to surface them before signing. If you receive a blocking `400`, validate the query or change the order inputs before retrying; repeating the unchanged request won't succeed.

## `503 Service Unavailable`

A `503` from the GMX API means the request couldn't be served at that moment. Unlike a `400`, the same request can succeed later, so retry with backoff.

- `/yield/gm-user-earnings` returns `503` while earnings data is warming up on a deployment, or on a deployment where it isn't available.
- `/stats/*` returns `503` on a deployment that doesn't serve protocol stats. The production hosts route `/v1/stats` to the Arbitrum deployment; if you still get a `503`, call an Arbitrum host directly.
- `/pairs/solana` returns `503` on a deployment that doesn't compute the GMX on Solana pair feed, and while its snapshot is still being built or is older than 15 minutes. Only the Arbitrum deployment computes it, and aggregators read it at `https://solana.gmxapi.io/v1/pairs`.
- `POST /orders/txns/prepare` and other routes return `503` when the request runs past the `60` second server timeout.
- `POST /gmx-account/withdraw/cross-chain/submit` returns `503` when the relay times out or is unavailable. The outcome is unknown because the relay may already hold the operation, so don't sign a new withdrawal. `POST /gmx-account/withdraw/cross-chain/status` usually reports `relay_unknown` for the request, and that status can't change until a submit gets a `taskId`, so you must resend the same signed body with the same `requestId` on the same base URL. A resend can't execute the withdrawal twice. After a resend gets a `taskId`, status stays `relay_unknown` until the relay reports a final result. You can resend until `relayParams.deadline`, one hour after prepare. After that, a resend returns `400`, status stays `relay_unknown`, and the withdrawal can no longer execute. Once a block's timestamp is past the deadline, read `digests` on `relayRouterAddress`, on the network of the base URL you used, for the EIP-712 hash of the typed data, and prepare a new withdrawal only if it returns `false`. The `503` body has no `code` or `requestId`, so keep the `requestId` from the prepare response. With SDK v2, use `prepareCrossChainWithdraw`, `signCrossChainWithdraw`, and `submitCrossChainWithdraw` when you need to be able to resend, because `executeCrossChainWithdraw` doesn't return the signed body after a failed submit. A `4xx` on a first submit means nothing was relayed, but a `4xx` on a resend doesn't tell you what happened to the earlier attempt.
- A `503` whose body has `code: "BACKEND_UNAVAILABLE"` means the request reached a GMX API pool that doesn't serve that route. Retry, and if it persists, report it with the `X-Trace-Id` response header.
- On the `.ai` base URLs, a `503` from the API reaches the client as a `504` with an HTML body; handle it like a `503`. The exception is the generic `/relay/*` routes: only the `.io` base URLs serve them, so don't retry them on `.ai`, and send them to the `.io` base URL of the same network.

On the `.io` base URLs, for the earnings, stats, Solana pair feed, and withdrawal submit cases, the response body is the generic `{"message":"Internal Server Error"}`, so use the route and the `X-Trace-Id` header, not the message, to tell the cases apart.

## A value looks stale

Start by checking whether you are reading from a cached or indexed surface.

- Use Oracle API `/markets/info` when you need near-live market state.
- Use Oracle API `/markets` when a `10` second cache window is acceptable.
- Use GraphQL for historical activity, not for the latest write-path state.
- Use a single composite read where possible instead of stitching unrelated polls together.

For GMX API market values, inspect each `/v1/markets/values` row's `updatedAt` field. It is a Unix timestamp in milliseconds and uses the older timestamp from the main market-values refresh and the `virtualInventoryForPositionsInTokens` refresh. A `null` value means at least one component has no successful refresh timestamp.

The default backend pulls market values every `5` seconds and marks a row stale for monitoring after `15` seconds. This threshold does not evict the row:

- A total pull failure preserves the previous values and timestamps, which continue to age.
- A market-specific failed refresh can preserve the previous values while setting `updatedAt` to `null`.
- Disabled markets are excluded from backend values-staleness accounting.

Compare `updatedAt` with a freshness limit appropriate for your application. Don't treat an HTTP `200` response as proof that every value came from the latest pull.

For GMX API protocol stats (`/stats/*`), check the response metadata before trusting a total:

- `meta.completeness` is `partial` when any source in scope isn't `fresh`. Stale sources still count toward the sums; missing sources are left out of them.
- `meta.sources[]` reports each source's `health` (`fresh`, `stale`, or `missing`), `lagSeconds`, and `lastError`. A source becomes `stale` when its data lags by more than `900` seconds, or `1800` seconds for the GMX on Solana source.
- Timeseries points with `provisional: true` cover days that can still change, and so can the four days before the current day.
- `tvl.poolsValuedAt` and `tvl.valuedAt` report when TVL was valued.

For `/yield/gm-user-earnings`, `window.endTimestamp` reports when the earnings were calculated.

If you need one coherent account snapshot, prefer one positions call with `includeRelatedOrders: true` over multiple loosely coordinated reads.

## A write succeeded, but the API still does not show it

That is usually a surface mismatch or an operation that hasn't reached a final state.

- SDK v2 and GMX API `/orders/txns/*` endpoints prepare, submit, and track signed order intents. Persist their `requestId` and poll order status on the same GMX API host that served prepare. The `gmxapi.io` and `gmxapi.ai` peers don't share order records, so status on the other peer returns `404` with the message `Transaction not found`. Don't fail over to the peer for that `requestId`; prepare the order again if the original host can't continue the chain. See [Idempotency and race conditions](./integration-guide.md#idempotency-and-race-conditions).
- The low-level GMX Relay surface accepts already-built relay-router calldata through `POST /relay/submit`. Persist the returned `taskId` and poll it through `POST /relay/status`.
- SDK v1 and direct contracts submit transactions from your wallet or backend RPC client. Wait for the transaction receipt, then poll the read surface you care about.

Generic relay statuses are `pending`, `executed`, `reverted`, `failed`, and `unknown`. Treat `unknown` as inconclusive rather than failed: keep the operation pending until your own timeout, and don't resubmit the same signed calldata blindly. A `404` immediately after an accepted submission can also be transient while status becomes readable.

For a reverted relay operation, inspect `reason` and the top-level `revertData` when present. `revertData` contains public on-chain revert bytes and can be decoded by the client. If submission fails before returning a `taskId`, capture the `X-Trace-Id` response header; it may be the only support identifier.

Don't assume the first follow-up HTTP or GraphQL read will reflect final state. Relay processing, transaction inclusion, keeper execution, and indexing can complete at different times.

## Positions and orders do not line up

If your UI shows position state together with linked orders, fetch them from the same logical snapshot.

Recommended pattern:

```typescript

const apiSdk = new GmxApiSdk({ chainId: 42161 });

const positions = await apiSdk.fetchPositionsInfo({
  address: "0x9f7198eb1b9Ccc0Eb7A07eD228d8FbC12963ea33",
  includeRelatedOrders: true,
});
```

Use a separate account-wide orders read only when you need a dedicated orders screen.

## There is no documented public SLA

The current manual docs do not publish a public SLA for these surfaces. Build your client as if network errors, timeouts, or stale snapshots can happen.

Recommended client behavior:

1. Use endpoint-specific fallback URLs where they are documented.
2. Add retries with backoff for safe read operations.
3. Keep write confirmation logic separate from read polling logic.
4. Log the exact surface you queried so you can distinguish GMX API, Oracle API, GraphQL, and SDK-backed reads during incident review.
5. Capture the `X-Trace-Id` response header for GMX API failures. It is exposed to browser clients through CORS; include it with any `requestId` or `taskId` in support reports.

## Next steps

- Use the [Integration guide](./integration-guide.md) for workflow selection.
- Use [Fallback URLs](./rest-api/fallback-urls.mdx) for Oracle API public read failover.
