API Errors

The CDP API uses conventional HTTP response codes to indicate the success or failure of an API request. In general:

• Codes in the 2xx range indicate success

• Codes in the 4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted)

• Codes in the 5xx range indicate an error on CDP’s backend servers.

  5xx errors are not a guarantee of failure; there’s always the chance that the operation may have succeeded in our back-end. Therefore, your application should treat the operation’s status as unknown.

Each error response includes:

• errorType: A machine-readable error code
• errorMessage: A human-readable message providing more detail
• correlationId: A unique identifier for the request that can help with debugging
• errorLink: A link to detailed documentation about the specific error type

HTTP 400

invalid_request

This error occurs when the request is malformed or contains invalid data, including issues with the request body, query parameters, path parameters, or headers.

Steps to resolve:

1. Check all required fields and parameters are present
2. Ensure request body (if applicable) follows the correct schema
3. Verify all parameter formats match the API specification:
   • Query parameters
   • Path parameters
   • Request headers
4. Validate any addresses, IDs, or other formatted strings meet requirements

Common validation issues:

• Missing required parameters
• Invalid parameter types or formats
• Malformed JSON in request body
• Invalid enum values

Example 1:

{
  "errorType": "invalid_request",
  "errorMessage": "Project has no secret. Please register a secret with the project.",
  "correlationId": "41deb8d59a9dc9a7-IAD",
  "errorLink": "https://docs.cdp.coinbase.com/api/v2/docs/errors#invalid_request"
}

Example 2:

{
  "errorType": "invalid_request",
  "errorMessage": "request body has an error: doesn't match schema: Error at \"name\": string doesn't match the regular expression \"^[A-Za-z0-9][A-Za-z0-9-]{0,34}[A-Za-z0-9]$\"",
  "correlationId": "41deb8d59a9dc9a7-IAD",
  "errorLink": "https://docs.cdp.coinbase.com/api/v2/docs/errors#invalid_request"
}

Example 3:

{
  "errorType": "invalid_request",
  "errorMessage": "Request body must be specified.",
  "correlationId": "41deb8d59a9dc9a7-IAD",
  "errorLink": "https://docs.cdp.coinbase.com/api/v2/docs/errors#invalid_request"
}

malformed_transaction

This error occurs when the transaction data provided is not properly formatted or is invalid.

Steps to resolve:

1. Verify transaction encoding:
   • EVM networks: Check RLP encoding is correct
   • Solana: Validate base64 encoding
2. Ensure all required transaction fields are present
3. Validate transaction parameters are within acceptable ranges
4. Check that the transaction type is supported on the target network

Common causes:

• Invalid hex encoding for EVM transactions
• Missing required transaction fields
• Incorrect parameter formats
• Unsupported transaction types
• Network-specific transaction format mismatches

Example error response:

{
  "errorType": "malformed_transaction",
  "errorMessage": "Malformed unsigned transaction.",
  "correlationId": "41deb8d59a9dc9a7-IAD",
  "errorLink": "https://docs.cdp.coinbase.com/api/v2/docs/errors#malformed_transaction"
}

invalid_signature

This error occurs when the signature provided for the given user operation is invalid.

Steps to resolve:

1. Verify the signature was generated by the correct owner account
2. Ensure the signature corresponds to the exact user operation hash
3. Check that the signature format matches the expected format
4. Confirm you’re using the correct network for the Smart Account

Common causes:

• Using wrong owner account to sign
• Signing modified/incorrect user operation data
• Malformed signature encoding
• Network mismatch between signature and broadcast

Example error response:

{
  "errorType": "invalid_signature",
  "errorMessage": "Invalid signature.",
  "correlationId": "41deb8d59a9dc9a7-IAD",
  "errorLink": "https://docs.cdp.coinbase.com/api/v2/docs/errors#invalid_signature"
}

HTTP 401

unauthorized

This error occurs when authentication fails.

Steps to resolve:

1. Verify your CDP API credentials:
   • Check that your API key is valid
   • Check that your Wallet Secret is properly configured
2. Validate JWT token:
   • Not expired
   • Properly signed
   • Contains required claims
3. Check request headers:
   • Authorization header present
   • X-Wallet-Auth header included when required

Security note: Never share your Wallet Secret or API keys.

Example error response:

{
  "errorType": "unauthorized",
  "errorMessage": "Wallet authentication error.",
  "correlationId": "41deb8d59a9dc9a7-IAD",
  "errorLink": "https://docs.cdp.coinbase.com/api/v2/docs/errors#unauthorized"
}

HTTP 403

forbidden

This error occurs when you don’t have permission to access the resource.

Steps to resolve:

1. Verify your permissions to access the resource
2. Ensure that you are the owner of the requested resource

Example 1:

{
  "errorType": "forbidden",
  "errorMessage": "Unable to sign transaction for this address.",
  "correlationId": "41deb8d59a9dc9a7-IAD",
  "errorLink": "https://docs.cdp.coinbase.com/api/v2/docs/errors#forbidden"
}

Example 2:

{
  "errorType": "forbidden",
  "errorMessage": "Unable to request faucet funds for this address.",
  "correlationId": "41deb8d59a9dc9a7-IAD",
  "errorLink": "https://docs.cdp.coinbase.com/api/v2/docs/errors#forbidden"
}

HTTP 404

not_found

This error occurs when the resource specified in your request doesn’t exist or you don’t have access to it.

Steps to resolve:

1. Verify the resource ID/address/account exists
2. Check your permissions to access the resource
3. Ensure you’re using the correct network/environment
4. Confirm the resource hasn’t been deleted

Common causes:

• Mistyped addresses
• Accessing resources from the wrong CDP project
• Resource was deleted or hasn’t been created yet

Example 1:

{
  "errorType": "not_found",
  "errorMessage": "EVM account with the given address not found.",
  "correlationId": "41deb8d59a9dc9a7-IAD",
  "errorLink": "https://docs.cdp.coinbase.com/api/v2/docs/errors#not_found"
}

Example 2:

{
  "errorType": "not_found",
  "errorMessage": "Smart Account with the given address not found.",
  "correlationId": "41deb8d59a9dc9a7-IAD",
  "errorLink": "https://docs.cdp.coinbase.com/api/v2/docs/errors#not_found"
}

Example 3:

{
  "errorType": "not_found",
  "errorMessage": "EVM smart account with the given address not found.",
  "correlationId": "41deb8d59a9dc9a7-IAD",
  "errorLink": "https://docs.cdp.coinbase.com/api/v2/docs/errors#not_found"
}

HTTP 409

already_exists

This error occurs when trying to create a resource that already exists.

Steps to resolve:

1. Check if the resource exists before creation
2. Use GET endpoints to verify resource state
3. Use unique identifiers/names for resources

Example 1:

{
  "errorType": "already_exists",
  "errorMessage": "EVM account with the given name already exists.",
  "correlationId": "41deb8d59a9dc9a7-IAD",
  "errorLink": "https://docs.cdp.coinbase.com/api/v2/docs/errors#already_exists"
}

Example 2:

{
  "errorType": "already_exists",
  "errorMessage": "Another request with the same idempotency key is currently processing.",
  "correlationId": "41deb8d59a9dc9a7-IAD",
  "errorLink": "https://docs.cdp.coinbase.com/api/v2/docs/errors#already_exists"
}

Example 3:

{
  "errorType": "already_exists",
  "errorMessage": "Solana account with the given name already exists.",
  "correlationId": "41deb8d59a9dc9a7-IAD",
  "errorLink": "https://docs.cdp.coinbase.com/api/v2/docs/errors#already_exists"
}

HTTP 422

idempotency_error

This error occurs when an idempotency key is reused with different parameters.

Steps to resolve:

1. Generate a new UUID v4 for each unique request
2. Only reuse idempotency keys for exact request duplicates
3. Track used keys within your application

Example idempotency key implementation:

import { v4 as uuidv4 } from 'uuid';

function createIdempotencyKey() {
  return uuidv4();
}

Example error response:

{
  "errorType": "idempotency_error",
  "errorMessage": "Idempotency key '8e03978e-40d5-43e8-bc93-6894a57f9324' was already used with a different request payload. Please try again with a new idempotency key.",
  "correlationId": "41deb8d59a9dc9a7-IAD",
  "errorLink": "https://docs.cdp.coinbase.com/api/v2/docs/errors#idempotency_error"
}

HTTP 429

faucet_limit_exceeded

This error occurs when you’ve exceeded the faucet request limits.

Steps to resolve:

1. Wait for the time window to reset
2. Use funds more efficiently in your testing

For more information on faucet limits, please visit the EVM Faucet endpoint or the Solana Faucet endpoint.

Example error response:

{
  "errorType": "faucet_limit_exceeded",
  "errorMessage": "Faucet limit reached for this address. Please try again later.",
  "correlationId": "41deb8d59a9dc9a7-IAD",
  "errorLink": "https://docs.cdp.coinbase.com/api/v2/docs/errors#faucet_limit_exceeded"
}

HTTP 500

internal_server_error

This indicates an unexpected error that occurred on the CDP servers.

Important: If you encounter this error, please note that your operation’s status should be treated as unknown by your application, as it could have been a success within the CDP back-end.

Steps to resolve:

1. Retry your request after a short delay
2. If persistent, contact CDP support with:
   • Your correlation ID
   • Timestamp of the error
   • Request details
3. Consider implementing retry logic with an exponential backoff

Note: These errors are automatically logged and monitored by CDP.

Example error response:

{
  "errorType": "internal_server_error",
  "errorMessage": "An internal server error occurred. Please try again later.",
  "correlationId": "41deb8d59a9dc9a7-IAD",
  "errorLink": "https://docs.cdp.coinbase.com/api/v2/docs/errors#internal_server_error"
}