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:

Check all required fields and parameters are present
Ensure request body (if applicable) follows the correct schema
Verify all parameter formats match the API specification:
- Query parameters
- Path parameters
- Request headers
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-reference/v2/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-reference/v2/errors#invalid_request"
}

Example 3:

{
  "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-reference/v2/errors#invalid_request"
}

malformed_transaction

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

Steps to resolve:

Verify transaction encoding:
- EVM networks: Check RLP encoding is correct
- Solana: Validate base64 encoding
Ensure all required transaction fields are present
Validate transaction parameters are within acceptable ranges
Check that the transaction type is supported on the target network (see our Supported Networks page for more details)

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-reference/v2/errors#malformed_transaction"
}

invalid_signature

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

Steps to resolve:

Verify the signature was generated by the correct owner account
Ensure the signature corresponds to the exact user operation hash
Check that the signature format matches the expected format
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-reference/v2/errors#invalid_signature"
}

policy_in_use

This error occurs when trying to delete a Policy that is currently in use by at least one project or account.

Steps to resolve:

Update project or accounts to remove references to the Policy in question.
Retry your delete request.

Example error response:

{
  "errorType": "policy_in_use",
  "errorMessage": "Policy in use",
  "correlationId": "41deb8d59a9dc9a7-IAD",
  "errorLink": "https://docs.cdp.coinbase.com/api-reference/v2/errors#policy_in_use"
}

HTTP 401

unauthorized

This error occurs when authentication fails.

Steps to resolve:

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

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

Example 1:

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

Example 2:

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

HTTP 402

payment_method_required

This error occurs when a payment method is required to complete the requested operation but none is configured or available.

Steps to resolve:

Add a valid payment method to your account using the CDP Portal
Ensure your payment method is valid and not expired

Common causes:

No payment method configured on the account
Payment method is expired

Example error response:

{
  "errorType": "payment_method_required",
  "errorMessage": "A valid payment method is required to complete this operation. Please add a payment method to your account at https://portal.cdp.coinbase.com.",
  "correlationId": "41deb8d59a9dc9a7-IAD",
  "errorLink": "https://docs.cdp.coinbase.com/api-reference/v2/errors#payment_method_required"
}

HTTP 403

forbidden

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

Steps to resolve:

Verify your permissions to access the resource
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-reference/v2/errors#forbidden"
}

Example 2:

{
  "errorType": "forbidden",
  "errorMessage": "Taker not permitted to perform swap.",
  "correlationId": "41deb8d59a9dc9a7-IAD",
  "errorLink": "https://docs.cdp.coinbase.com/api-reference/v2/errors#forbidden"
}

Example 3:

{
  "errorType": "forbidden",
  "errorMessage": "Unable to request faucet funds for this address.",
  "correlationId": "41deb8d59a9dc9a7-IAD",
  "errorLink": "https://docs.cdp.coinbase.com/api-reference/v2/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:

Verify the resource ID/address/account exists
Check your permissions to access the resource
Ensure you’re using the correct network/environment
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-reference/v2/errors#not_found"
}

Example 2:

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

Example 3:

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

HTTP 409

already_exists

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

Steps to resolve:

Check if the resource exists before creation
Use GET endpoints to verify resource state
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-reference/v2/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-reference/v2/errors#already_exists"
}

Example 3:

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

HTTP 422

idempotency_error

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

Steps to resolve:

Generate a new UUID v4 for each unique request
Only reuse idempotency keys for exact request duplicates
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-reference/v2/errors#idempotency_error"
}

HTTP 429

rate_limit_exceeded

This error occurs when you’ve exceeded the API rate limits.

Steps to resolve:

Implement exponential backoff
Cache responses where possible
Wait for rate limit window to reset

Best practices:

async function withRetry(fn: () => Promise<any>) {
  let delay = 1000;
  while (true) {
    try {
      return await fn();
    } catch (e) {
      if (e.errorType === "rate_limit_exceeded") {
        await sleep(delay);
        delay *= 2;
        continue;
      }
      throw e;
    }
  }
}

Example 1:

{
  "errorType": "rate_limit_exceeded",
  "errorMessage": "Max concurrent user operations reached.",
  "correlationId": "41deb8d59a9dc9a7-IAD",
  "errorLink": "https://docs.cdp.coinbase.com/api-reference/v2/errors#rate_limit_exceeded"
}

Example 2:

{
  "errorType": "rate_limit_exceeded",
  "errorMessage": "Rate limit exceeded.",
  "correlationId": "41deb8d59a9dc9a7-IAD",
  "errorLink": "https://docs.cdp.coinbase.com/api-reference/v2/errors#rate_limit_exceeded"
}

faucet_limit_exceeded

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

Steps to resolve:

Wait for the time window to reset
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-reference/v2/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:

Retry your request after a short delay
If persistent, contact CDP support with:
- Your correlation ID
- Timestamp of the error
- Request details
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-reference/v2/errors#internal_server_error"
}

HTTP 502

bad_gateway

This error occurs when the CDP API is unable to connect to the backend service.

Steps to resolve:

Retry your request after a short delay
If persistent, contact CDP support with:
- The timestamp of the error
- Request details
Consider implementing retry logic with an exponential backoff

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

Example error response:

{
  "errorType": "bad_gateway",
  "errorMessage": "Bad gateway. Please try again later.",
  "correlationId": "41deb8d59a9dc9a7-IAD",
  "errorLink": "https://docs.cdp.coinbase.com/api-reference/v2/errors#bad_gateway"
}

HTTP 503

service_unavailable

This error occurs when the CDP API is temporarily unable to handle requests due to maintenance or high load.

Steps to resolve:

Retry your request after a short delay
If persistent, contact CDP support with:
- The timestamp of the error
- Request details
Consider implementing retry logic with an exponential backoff

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

Example error response:

{
  "errorType": "service_unavailable",
  "errorMessage": "Service unavailable. Please try again later.",
  "correlationId": "41deb8d59a9dc9a7-IAD",
  "errorLink": "https://docs.cdp.coinbase.com/api-reference/v2/errors#service_unavailable"
}

Network Errors

Network errors occur when there is a problem establishing or maintaining a connection to the CDP API at the network layer. These errors are distinct from API service errors - they indicate that your request never reached the CDP API or was blocked before it could be processed.

Understanding Network Errors

When you encounter a network error via the CDP SDK, you’ll receive a NetworkError object with:

statusCode: Always 0 (indicating no HTTP response was received)
errorType: Specific type of network error
errorMessage: Human-readable description
networkDetails: Additional information including:
- code: Technical error code
- message: Original error message
- retryable: Whether the operation should be retried

Types of Network Errors

1. IP Blocked (`network_ip_blocked`)

Your IP address has been blocked at the gateway level.

Common causes:

Geographic restrictions.
Rate limiting at infrastructure level.
Security policies or DDoS protection.
Corporate firewall/proxy restrictions.

What to do:

Verify you’re not accessing from a restricted region.
Check if you’re behind a VPN or proxy that might be blocked.
Contact CDP support on Discord if you believe this is in error.
This error is not retryable.

2. Connection Failed (`network_connection_failed`)

Unable to establish a connection to the CDP API.

Common causes:

CDP API is temporarily unavailable. Check the CDP Status Page for any ongoing issues.
Network connectivity issues.
Firewall blocking outbound HTTPS connections.
Incorrect API endpoint configuration.

What to do:

Check your internet connection.
Verify firewall settings allow HTTPS traffic to api.cdp.coinbase.com.
Ensure you’re using the correct API endpoint.
This error is retryable. Retry the request with exponential backoff.

3. Timeout (`network_timeout`)

The request took too long and was terminated.

Common causes:

Network congestion.
Slow internet connection.

What to do:

Increase timeout settings if consistently timing out.
This error is retryable. Retry the request with exponential backoff.

4. DNS Failure (`network_dns_failure`)

Unable to resolve the CDP API domain name.

Common causes:

DNS configuration issues.
Network connectivity problems.
DNS server unavailable.
Incorrect API endpoint URL.

What to do:

Check your DNS settings.
Verify network connectivity with nslookup api.cdp.coinbase.com.
Try using a different DNS server (e.g., 8.8.8.8).
Ensure the API URL is correct.
This error is not retryable until DNS is fixed.

Handling Network Errors in Code

import { NetworkError } from '@coinbase/cdp-sdk';

try {
  const account = await cdp.evm.getAccount({ address: '0x...' });
} catch (error) {
  if (error instanceof NetworkError) {
    console.error(`Network error: ` + error.errorMessage);
    console.error(`Type: ` + error.errorType);
    console.error(`Details:` + error.networkDetails);
    
    // Check if the error is retryable
    if (error.networkDetails?.retryable) {
      // Implement retry logic with exponential backoff
      await retryWithBackoff(async () => {
        return await cdp.evm.getAccount({ address: '0x...' });
      });
    } else {
      // Handle non-retryable errors
      if (error.errorType === "network_ip_blocked") {
        console.error('Your IP appears to be blocked. Please check your network configuration.');
      }
    }
  }
}

Best Practices

Implement Retry Logic: For retryable errors, use exponential backoff:

async function retryWithBackoff<T>(
  fn: () => Promise<T>,
  maxRetries = 3,
  baseDelay = 1000
): Promise<T> {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await fn();
    } catch (error) {
      if (error instanceof NetworkError && error.networkDetails?.retryable && i < maxRetries - 1) {
        await new Promise(resolve => setTimeout(resolve, baseDelay * Math.pow(2, i)));
        continue;
      }
      throw error;
    }
  }
  throw new Error('Max retries exceeded');
}

Log Network Errors: Always log network errors with full details for debugging.
Monitor Patterns: Track network errors to identify patterns (time of day, specific operations, etc.).
Have Fallback Strategies: Consider implementing fallback mechanisms for critical operations.

Troubleshooting Checklist

Verify internet connectivity.
Check if you’re behind a proxy or VPN.
Ensure firewall allows HTTPS traffic to api.cdp.coinbase.com.
Verify you’re not in a restricted geographic region.
Check DNS resolution: nslookup api.cdp.coinbase.com.
Test with curl or similar: curl -I https://api.cdp.coinbase.com/platform.
Check if the issue is consistent or intermittent.

Getting Help

If you continue to experience network errors after following this guide:

Collect error details including:
- Full error message and type.
- Network details from the error.
- Time and frequency of occurrence.
- Your network configuration (proxy, VPN, region).
Contact CDP support on Discord with this information.
Check the CDP Status Page for any ongoing issues.

Remember: Network errors are typically environmental issues rather than code problems. Focus on network configuration and connectivity when troubleshooting.

CDP API V2

REST API

​API Errors

​HTTP 400

​invalid_request

​malformed_transaction

​invalid_signature

​policy_in_use

​HTTP 401

​unauthorized

​HTTP 402

​payment_method_required

​HTTP 403

​forbidden

​HTTP 404

​not_found

​HTTP 409

​already_exists

​HTTP 422

​idempotency_error

​HTTP 429

​rate_limit_exceeded

​faucet_limit_exceeded

​HTTP 500

​internal_server_error

​HTTP 502

​bad_gateway

​HTTP 503

​service_unavailable

​Network Errors

​Understanding Network Errors

​Types of Network Errors

​1. IP Blocked (network_ip_blocked)

​2. Connection Failed (network_connection_failed)

​3. Timeout (network_timeout)

​4. DNS Failure (network_dns_failure)

​Handling Network Errors in Code

​Best Practices

​Troubleshooting Checklist

​Getting Help

API Errors

HTTP 400

invalid_request

malformed_transaction

invalid_signature

policy_in_use

HTTP 401

unauthorized

HTTP 402

payment_method_required

HTTP 403

forbidden

HTTP 404

not_found

HTTP 409

already_exists

HTTP 422

idempotency_error

HTTP 429

rate_limit_exceeded

faucet_limit_exceeded

HTTP 500

internal_server_error

HTTP 502

bad_gateway

HTTP 503

service_unavailable

Network Errors

Understanding Network Errors

Types of Network Errors

1. IP Blocked (`network_ip_blocked`)

2. Connection Failed (`network_connection_failed`)

3. Timeout (`network_timeout`)

4. DNS Failure (`network_dns_failure`)

Handling Network Errors in Code

Best Practices

Troubleshooting Checklist

Getting Help