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

errorType indicates the category of error, while errorMessage provides specific details about what went wrong.Some validation failures have dedicated error types (e.g., transfer_amount_out_of_bounds, transfer_quote_expired), while others return invalid_request with a descriptive message explaining the specific validation failure. The errorMessage is designed to be human-readable and can be displayed directly to understand or communicate what went wrong.

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: Invalid query parameters

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

Example: Invalid account creation request

{
  "errorType": "invalid_request",
  "errorMessage": "Invalid account creation request.",
  "correlationId": "41deb8d59a9dc9a7-IAD",
  "errorLink": "https://docs.cdp.coinbase.com/api-reference/v2/errors#invalid_request"
}

Example: Invalid account ID

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

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 payment method is required to complete this operation.",
  "correlationId": "41deb8d59a9dc9a7-IAD",
  "errorLink": "https://docs.cdp.coinbase.com/api-reference/v2/errors#payment_method_required"
}

transfer_amount_out_of_bounds

This error occurs when the transfer amount is less than $1 USD equivalent amount or greater than the maximum transfer amount for the account. Steps to resolve:

Verify the transfer amount is greater than $1 USD equivalent amount.
Confirm that the account has sufficient funds to cover the transfer amount.

Example error response:

{
  "errorType": "transfer_amount_out_of_bounds",
  "errorMessage": "Transfer amount must be at least $1.00 USD equivalent.",
  "correlationId": "41deb8d59a9dc9a7-IAD",
  "errorLink": "https://docs.cdp.coinbase.com/api-reference/v2/errors#transfer_amount_out_of_bounds"
}

transfer_recipient_address_invalid

This error occurs when the recipient address is invalid for the specified network. Steps to resolve:

Verify the network is supported for the transfer.
Confirm that the recipient address is valid for the specified network.

Example error response:

{
  "errorType": "transfer_recipient_address_invalid",
  "errorMessage": "The recipient address is invalid for the specified network.",
  "correlationId": "41deb8d59a9dc9a7-IAD",
  "errorLink": "https://docs.cdp.coinbase.com/api-reference/v2/errors#transfer_recipient_address_invalid"
}

transfer_quote_expired

This error occurs when the transfer quote has expired. Steps to resolve:

Create a new transfer quote and retry the request.

Example error response:

{
  "errorType": "transfer_quote_expired",
  "errorMessage": "The transfer quote has expired. Please create a new transfer.",
  "correlationId": "41deb8d59a9dc9a7-IAD",
  "errorLink": "https://docs.cdp.coinbase.com/api-reference/v2/errors#transfer_quote_expired"
}

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: Session authentication required

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

Example: Authentication required

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

Example: Authentication error

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

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 error response:

{
  "errorType": "forbidden",
  "errorMessage": "You do not have permission to link this account.",
  "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: Account not found

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

Example: Account or asset not found

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

Example: Transfer not found

{
  "errorType": "not_found",
  "errorMessage": "Transfer 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 error response:

{
  "errorType": "already_exists",
  "errorMessage": "Payment method with these details 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

Example: Rate limit exceeded

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

Example: Too many requests. Please try again later

{
  "errorType": "rate_limit_exceeded",
  "errorMessage": "Too many requests. Please try again later.",
  "correlationId": "41deb8d59a9dc9a7-IAD",
  "errorLink": "https://docs.cdp.coinbase.com/api-reference/v2/errors#rate_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: An internal server error occurred

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

Example: An internal server error occurred. Please try again later

{
  "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"
}

CDP PAYMENTS API

REST API

Errors

API Errors

HTTP 400

invalid_request

payment_method_required

transfer_amount_out_of_bounds

transfer_recipient_address_invalid

transfer_quote_expired

HTTP 401

unauthorized

HTTP 403

forbidden

HTTP 404

not_found

HTTP 409

already_exists

HTTP 422

idempotency_error

HTTP 429

rate_limit_exceeded

HTTP 500

internal_server_error

HTTP 502

bad_gateway

HTTP 503

service_unavailable

CDP PAYMENTS API

REST API

​API Errors

​HTTP 400

​invalid_request

​payment_method_required

​transfer_amount_out_of_bounds

​transfer_recipient_address_invalid

​transfer_quote_expired

​HTTP 401

​unauthorized

​HTTP 403

​forbidden

​HTTP 404

​not_found

​HTTP 409

​already_exists

​HTTP 422

​idempotency_error

​HTTP 429

​rate_limit_exceeded

​HTTP 500

​internal_server_error

​HTTP 502

​bad_gateway

​HTTP 503

​service_unavailable

API Errors

HTTP 400

invalid_request

payment_method_required

transfer_amount_out_of_bounds

transfer_recipient_address_invalid

transfer_quote_expired

HTTP 401

unauthorized

HTTP 403

forbidden

HTTP 404

not_found

HTTP 409

already_exists

HTTP 422

idempotency_error

HTTP 429

rate_limit_exceeded

HTTP 500

internal_server_error

HTTP 502

bad_gateway

HTTP 503

service_unavailable