{"record":{"id":"ea9eda844b42f40c","repo":"firecrawl/firecrawl","slug":"failed-to-get-token-usage-error-response-json-ea9eda","errorCode":null,"errorMessage":"Failed to get token usage. Error: {response_json}","messagePattern":"Failed to get token usage\\. Error: (.+?)","errorType":"exception","errorClass":"Exception","httpStatus":null,"severity":"warning","filePath":"apps/python-sdk/firecrawl/v1/client.py","lineNumber":823,"sourceCode":"            self._handle_error(response, 'get credit usage')\n\n    def get_token_usage(self) -> V1TokenUsageResponse:\n        \"\"\"Get current token usage and billing period (v1).\"\"\"\n        _headers = self._prepare_headers()\n        response = self._get_request(\n            f\"{self.api_url}/v1/team/token-usage\",\n            _headers\n        )\n\n        if response.status_code == 200:\n            try:\n                response_json = response.json()\n                if response_json.get('success') and 'data' in response_json:\n                    return V1TokenUsageResponse(**response_json)\n                elif \"error\" in response_json:\n                    raise Exception(f\"Failed to get token usage. Error: {response_json['error']}\")\n                else:\n                    raise Exception(f\"Failed to get token usage. Error: {response_json}\")\n            except ValueError:\n                raise Exception('Failed to parse Firecrawl response as JSON.')\n        else:\n            self._handle_error(response, 'get token usage')\n\n    def get_credit_usage_historical(self, by_api_key: bool = False) -> V1CreditUsageHistoricalResponse:\n        \"\"\"Get historical credit usage (v1).\"\"\"\n        _headers = self._prepare_headers()\n        url = f\"{self.api_url}/v1/team/credit-usage/historical\" + (\"?byApiKey=true\" if by_api_key else \"\")\n        response = self._get_request(url, _headers)\n\n        if response.status_code == 200:\n            try:\n                response_json = response.json()\n                if response_json.get('success') and 'periods' in response_json:\n                    return V1CreditUsageHistoricalResponse(**response_json)\n                elif \"error\" in response_json:\n                    raise Exception(f\"Failed to get historical credit usage. Error: {response_json['error']}\")","sourceCodeStart":805,"sourceCodeEnd":841,"githubUrl":"https://github.com/firecrawl/firecrawl/blob/656bffcc2883f1af5befe38766b1ff5f0469993a/apps/python-sdk/firecrawl/v1/client.py#L805-L841","documentation":"Raised by get_token_usage after a 200 response whose body is neither success+data nor contains an 'error' key. The full response_json is stringified because the server returned an unexpected schema.","triggerScenarios":"SDK/server version mismatch; proxy returning a non-conforming body for the token-usage endpoint.","commonSituations":"Outdated SDK against newer cloud API; intermediary gateway rewriting the response.","solutions":["Upgrade firecrawl-py to the latest release.","Print str(e) to inspect the unexpected response_json.","Remove any transforming proxy.","Pin to a compatible SDK version if needed."],"exampleFix":"// before\nusage = app.get_token_usage()\n\n// after\ntry:\n    usage = app.get_token_usage()\nexcept Exception as e:\n    print(\"unexpected token-usage body:\", str(e))\n    raise","handlingStrategy":"try-catch","validationCode":"import firecrawl\nassert hasattr(firecrawl, '__version__'), 'pin SDK version'","typeGuard":"def is_expected_usage_shape(d: dict) -> bool:\n    return d.get('success') is True and 'data' in d","tryCatchPattern":"try:\n    usage = app.get_token_usage()\nexcept Exception as e:\n    if 'Failed to get token usage. Error:' in str(e) and '{' in str(e):\n        log.error('token-usage schema drift: %s', str(e))\n    raise","preventionTips":["Pin SDK version to match the server.","Log response_json on schema drift.","Bypass transforming proxies."],"tags":["billing","token-usage","response-shape","version-skew"],"analyzedSha":"656bffcc2883f1af5befe38766b1ff5f0469993a","analyzedAt":"2026-08-12T01:18:00.488Z","schemaVersion":2},"datasetVersion":"2026-08-12T06:17:24.410Z"}