Platform
Error Codes
When an API request fails, Gemini returns an HTTP 4xx or 5xx status code and a JSON response body detailing the failure.
HTTP Error Codes
| HTTP Status | Meaning |
|---|---|
| 200 | Request succeeded |
| 30x | API entry point moved. Check the Location header for redirect URL. |
| 400 | Market not open, malformed request, or invalid authentication headers |
| 403 | API key lacks the required role for this endpoint |
| 404 | Unknown endpoint or order not found |
| 406 | Insufficient funds |
| 429 | Rate limit exceeded |
| 500 | Server encountered an error |
| 502 | Technical issues prevented request fulfillment |
| 503 | Exchange is down for maintenance |
Error payload
Failed requests return a non-200 HTTP status code and a JSON body containing three fields:
result: Always"error".reason: A short machine-readable error identifier from the table below.message: A human-readable description of the error.
| Reason | Meaning |
|---|---|
| ClientOrderIdTooLong | Client Order ID must not exceed 100 characters |
| ClientOrderIdMustBeString | Client Order ID must be a string |
| ConflictingOptions | Selected order execution options conflict with each other |
| ConflictingAccountName | Specified name is already in use within the master group |
| EndpointMismatch | Request path does not match the endpoint specified in payload |
| EndpointNotFound | No endpoint specified |
| GTSTradeIDMustBeString | Clearing ID must be a string |
| InsufficientFunds | Order rejected due to insufficient funds |
| InvalidJson | Request body contains invalid JSON |
| InvalidNonce | Nonce is not strictly greater than previous nonce or falls outside +/- 30 seconds of server epoch |
| InvalidOrderType | Unsupported or unknown order type |
| InvalidPrice | Invalid price specified for order |
| InvalidStopPrice | Invalid stop price specified for stop-limit order |
| InvalidStopPriceSell | Stop price for stop-limit sell order was below the sell price |
| InvalidStopPriceBuy | Stop price for stop-limit buy order was above the buy price |
| InvalidStopPriceRatio | Stop price deviates more than 50% from the limit price |
| InvalidQuantity | Invalid or negative order quantity specified |
| InvalidSide | Invalid order side specified (must be buy or sell) |
| InvalidSignature | Request signature did not match payload and API secret |
| InvalidSymbol | Unknown or invalid symbol |
| InvalidTimestampInPayload | Payload contains an unsupported timestamp value |
| InvalidAccountName | Account name does not match any account in the master group |
| InvalidAccountType | Account type must be exchange or custody |
| InvalidFundTransfer | Internal fund transfer failed |
| Maintenance | Exchange is down for scheduled maintenance |
| MarketNotOpen | Market is currently not accepting new orders |
| MissingAccountName | Required account name omitted |
| MissingAccounts | Required account field omitted |
| MissingApikeyHeader | Missing X-GEMINI-APIKEY HTTP header |
| MissingOrderField | Required order_id field omitted |
| MissingRole | API key lacks the required role for this endpoint |
| MissingPayloadHeader | Missing X-GEMINI-PAYLOAD HTTP header |
| MissingPayloadKey | Payload is missing a required parameter |
| MissingSignatureHeader | Missing X-GEMINI-SIGNATURE HTTP header |
| MissingName | Required name field omitted |
| MissingNonce | Missing nonce in payload. See Private API Invocation. |
| MoreThanOneAccount | Multiple accounts supplied to a single-account endpoint |
| AccountClosed | Account is closed and cannot perform this operation |
| AccountsOnGroupOnlyApi | Account parameter supplied to a group-level endpoint using a non-master key |
| AccountLimitExceeded | Number of accounts exceeds the endpoint limit |
| NoAccountOfTypeRequired | Specified accounts do not match the required account type |
| AccountNotOfTypeRequired | Specified account does not match the required account type |
| NotGroupApiCompatible | Master API key used on an account-only endpoint |
| ExceededMaxAccountsInGroup | Cannot create account because master group reached its maximum limit |
| NoSSL | HTTPS is required for all API requests |
| OptionsMustBeArray | Parameter options must be an array |
| OrderNotFound | Specified order does not exist |
| RateLimit | Request rate exceeded. See Rate Limits. |
| System | Internal server error |
| UnsupportedOption | Specified order execution option is not supported |
| HasNotAgreedToCustodyTerms | Master group has not accepted Custody terms. Review and accept at https://exchange.gemini.com/custody. |
| BadAccountType | Parameter type must be exchange or custody |
| RemoteAddressForbidden | Request originated from an IP address not on the group allowlist |