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
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:
Copy
Ask AI
{ "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:
Copy
Ask AI
{ "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:
Copy
Ask AI
{ "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"}
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:
Copy
Ask AI
{ "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"}
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:
Copy
Ask AI
{ "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:
Copy
Ask AI
{ "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:
Copy
Ask AI
{ "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"}
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:
Copy
Ask AI
{ "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:
Copy
Ask AI
{ "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:
Copy
Ask AI
{ "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"}
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:
Copy
Ask AI
{ "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:
Copy
Ask AI
{ "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:
Copy
Ask AI
{ "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"}
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:
Copy
Ask AI
import { v4 as uuidv4 } from 'uuid';function createIdempotencyKey() { return uuidv4();}
Example error response:
Copy
Ask AI
{ "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"}
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:
Copy
Ask AI
{ "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"}
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.
Remember: Network errors are typically environmental issues rather than code problems. Focus on network configuration and connectivity when troubleshooting.