Debugging the Python API Client
There are two diagnostic options for the API Client —debug_mode and verbose. Both log network calls to the console; debug_mode additionally writes a log file recording every network request and the time it took. These tools help diagnose issues and give insight into request timings so you can write more performant code.
For example, running the snippet below:
_send_request() on the API Client to log additional state. The accompanying log file (named like cm_api_client_debug_2023_01_09_11_01_02.txt) is also useful when working with Coin Metrics customer success.
Common Errors
Proxy Error
Some organizations require all third-party requests to flow through a proxy. For proxies that don’t require auth:SSLError: SSL Certificate Verification
Some corporate networks have special rules for SSL certificate verification, leading to errors like:400 Bad Parameter
This error occurs when an invalid parameter value is passed, e.g.client.get_asset_metrics(assets='bad_asset_name') yields "Bad parameter 'assets'. Value 'bad_asset_name' is not supported.". Two ways to fix it:
- If the endpoint supports
ignore_unsupported_errors, set it toTrue. - Otherwise, use the
reference_dataandcatalog_v2methods to construct a query with valid parameter values. See this tutorial for an example.
401 Unauthorized
Your credentials are invalid — you may be using an invalid API key. Check the Getting Started guide for instructions on setting up the proper credentials.403 Forbidden
Your credentials are valid but not authorized for the requested data. Check the Getting Started guide for instructions on configuring credentials with the right permissions.414 URI Too Long
This error occurs when the HTTP URI generated by the client is too long. It commonly happens when passing a very large number of parameters, e.g.client.get_asset_metrics(assets=<long_list_of_assets>, ...) or client.get_list_of_balance_updates_v2(asset='btc', accounts=<long_list_of_accounts>).
Use the .parallel() method to bypass this issue, e.g.: client.get_asset_metrics(assets=<long_list_of_assets>).parallel(). Parallelization breaks up the request into chunks based on the parallelization variable, keeping each URI well under the limit.
This workaround only works for endpoints that allow parallelization. See ParallelDataCollection._VALID_PARALLEIZATION_PARAMS for the list of parallelizable variables and ParallelDataCollection._ENDPOINT_FIRST_PARAM_DICT for the per-endpoint defaults.
429 Too Many Requests
This error occurs when rate limits are exceeded. See API Rate Limits for more information. Retry logic was refactored in version2025.9.17.17 to better handle these errors. If you see this error often, we strongly recommend upgrading to 2025.9.17.17 or later.
