Debugging the Python API Client
There are two additional options for the API Client -debug_mode and verbose. These two options log network calls to the console, and in the case of debug_mode it will generate a log file of all the network requests and the time it takes to call them. These tools can be used to diagnose issues in your code and also to get a better understanding of request times so that users can write more performant code. For example, running the below code:
_send_request() method of the API Client to log additional data about the state of your environment, or anything else that would help diagnose issues. You will notice a log file generated in the format cm_api_client_debug_2023_01_09_11_01_02.txt. This log file might be helpful for your own use or to give more context if you are working with Coin Metrics customer success.
Proxy Error
Sometimes your organization has special rules on making requests to third parties and you have to use proxies in order to comply with the rules. For proxies that don’t require auth you can specify them similar to this example:SSLError: SSL Certs Verification
Sometimes your organization network have special rules on SSL certs verification and in this case you might face the following error when running the script:python3 -c "import requests; print(requests.certs.where())"And note that this will change based on whether or not you are using a Python virtual environment or not
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.". There are two ways to fix this:
- If the endpoint supports the
ignore_unsupported_errorsparameter, set this value to True. - Else, you will need to use the
reference_dataandcatalog_v2methods to properly construct a query with the valid parameter values. See this tutorial for an example.
401 Unauthorized
This error occurs when your credentials are invalid. You may be using an invalid API key. Check the Getting Started guide for instructions on how to get set up with the proper credentials.403 Forbidden
This error occurs when your credentials are valid but you may not be authorized to access the data, e.g.{"error": {"type": "forbidden","message": "Requested metric 'SplyBMXNtv' with frequency '1d' for asset 'btc' is not available with supplied credentials."}}
Reach out to https://coinmetrics.io/contact/ to expand your existing credentials. Check that your key has proper access to the data by going to coverage.coinmetrics.io.
To fix bypass this error with your current credentials, there are two options:
- If the endpoint supports the
ignore_forbidden_errorsparameter, set this value to True. - Else, you will need to use the
reference_dataandcatalog_v2methods to properly construct a query with the valid parameter values. See this tutorial for an example.
414 URI Too Long
This error occurs when the HTTP URI being passed using the Python API Client is too long. This is a common consequence of passing too many parameters in a given endpoints, 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 HTTP requests into chunks by the variable it is being parallelized on, resulting in URI(s) well under the limit.
Note this workaround works only for endpoints which allow parallelization. See the attribute ParallelDataCollection._VALID_PARALLEIZATION_PARAMS for the list of parallelizable variables and ParallelDataCollection._ENDPOINT_FIRST_PARAM_DICT for the dict of endpoints and default set of parallelizable variables.
429 Too Many Requests
This error occurs when the rate limits are exceeded. See the API Rate limits for more information. In version2025.9.17.17, retry logic was refactored to ensure that these errors are better handled by the API Client. If you are seeing this error often, we highly recommend upgrading to 2025.9.17.17 or later.
