Troubleshooting
Every error code from both variants, and how to fix them
Advanced Trade Error Codes
| Code | HTTP Status | Cause | Fix |
|---|---|---|---|
INVALID_CREDENTIAL | 401 / 403 | The CDP API key is missing, revoked, or the JWT signature is invalid. | Re-check the vault entry behind credentialId — both the Key ID and the EC (P-256) private key must be present and valid. |
COINBASE_PRODUCT_NOT_FOUND | 404 | The productId/orderId/etc. doesn't exist or isn't visible to this credential. | Double check the ID; list first (products/list, orders/list) if unsure. |
UPSTREAM_RATE_LIMITED | 429 | Too many requests. | Most operations auto-retry through the built-in rate-limit handler. Fund-moving operations that opt out (orders/create's idempotent path aside, converts/commitTrade, portfolios/moveFunds) surface the 429 directly — back off and retry manually. |
COINBASE_ORDER_REJECTED | 400, or 200 with success:false | The order/request was rejected — insufficient funds, invalid size, market closed, bad parameter, etc. | Read the accompanying message text (Coinbase's own reason) — the code itself is a deliberately broad bucket, not a guess at a more specific cause. |
UPSTREAM_ERROR | 5xx / unclassified | Coinbase-side failure or an unrecognized status code. | Transient — retry with backoff. |
Server Wallet Error Codes
| Code | HTTP Status | Cause | Fix |
|---|---|---|---|
INVALID_CREDENTIAL | 401 / 403 | The CDP API key is missing/invalid, or the required Wallet Secret is missing for an operation that needs it. | Check both credentialId and (where required) walletSecretCredentialId — see Configuration for which operations need which. |
CDP_ACCOUNT_NOT_FOUND | 404 | The accountName/address/policyId doesn't exist. | Confirm the name/address; account/getOrCreate will create it if missing rather than erroring. |
UPSTREAM_RATE_LIMITED | 429 | Too many requests. | Most operations auto-retry. swap/execute opts out — see AMBIGUOUS_OUTCOME_NO_RETRY below. |
IDEMPOTENCY_KEY_MISMATCH | 422, idempotency_error | A retried request reused an idempotency key against a request body that doesn't match the original attempt. | Don't change any field (amount, address, token) between a request and its retry — the whole point of the key is to detect exactly this. |
AMBIGUOUS_OUTCOME_NO_RETRY | timeout / 5xx | Currently only on swap/execute, which has no confirmed idempotency mechanism — the platform refuses to guess whether the swap actually happened. | Check the account's balance (balance/listTokens) or on-chain history before deciding whether to re-run the swap. Do not blindly retry. |
UPSTREAM_ERROR | unclassified | CDP-side failure or an unrecognized status/error shape. | Transient — retry with backoff (except swap/execute, see above). |
Common Configuration Mistakes
"Requires a CDP API key credential..." on every call: the vault entry behind
credentialId is missing either the Key ID (Username) or the private key (Password) half of the pair — both are required, on both variants.
"This operation moves funds and requires a Wallet Secret credential": you called a Server Wallet operation marked [wallet secret required] on its resource page without setting
walletSecretCredentialId. This includes five operations whose live requirement is unconfirmed but enforced fail-closed — see Configuration.
Order created but
orders/create still errored: check for COINBASE_ORDER_REJECTED with a 200 status — Coinbase can accept the HTTP call but reject the order body (success:false). The order was never placed in this case.