Errors
Every error has a stable code and says whether retrying can help.
{
"error": {
"code": "IDEMPOTENCY_KEY_CONFLICT",
"message": "IDEMPOTENCY_KEY_CONFLICT",
"retryable": false
}
}Branch on code. message is for people and may change. retryable is true only when sending the same request again may succeed. Every error the API returns today is false, so fix the request first; the exception is a 500, which is worth retrying later with the same Idempotency-Key.
| Status | Code | What to do |
|---|---|---|
| 400 | IDEMPOTENCY_KEY_REQUIRED | Add an Idempotency-Key header to the POST. |
| 400 | POLICY_NOT_FOUND | Give the wallet an active policy in the workspace. |
| 400 | VALIDATION_ERROR | Fix the request body or parameters to match the API reference. |
| 400 | INVALID_REQUEST_BODY | Send the body as valid JSON with Content-Type: application/json. |
| 400 | INVALID_CURSOR | Pass cursor exactly as the previous page's nextCursor returned it. |
| 400 | UNSUPPORTED_NETWORK | Register the wallet on a network that GET /v1/networks lists. |
| 400 | INVALID_EVM_ADDRESS, INVALID_SOLANA_ADDRESS, INVALID_STELLAR_ADDRESS, INVALID_SUI_ADDRESS | The address isn't valid for the wallet's network. Send it in full; a mixed-case EVM address must have a valid checksum. |
| 401 | UNAUTHENTICATED | Send a valid, enabled X-API-Key. A key that has used its daily request allowance is rejected until the allowance resets. |
| 403 | FORBIDDEN | Use a key with the access this endpoint needs. |
| 403 | STEP_UP_UNSUPPORTED_FOR_API_KEY | Do this in the workspace; API keys can't. |
| 404 | NOT_FOUND | Check the ID. It may belong to another organization. |
| 409 | IDEMPOTENCY_KEY_CONFLICT | Use a new key for a different request. |
| 409 | WALLET_ALREADY_EXISTS | The wallet is already registered; list wallets to find it. |
| 429 | WALLET_LIMIT_REACHED | Your organization has reached its wallet limit. Contact us. |
| 500 | INTERNAL_ERROR | Something failed on our side. Retry later with the same Idempotency-Key; contact us if it continues. |