firecrawl/firecrawl · warning · Exception

Failed to get token usage. Error: {response_json}

Error message

Failed to get token usage. Error: {response_json}

What it means

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.

Source

Thrown at apps/python-sdk/firecrawl/v1/client.py:823

            self._handle_error(response, 'get credit usage')

    def get_token_usage(self) -> V1TokenUsageResponse:
        """Get current token usage and billing period (v1)."""
        _headers = self._prepare_headers()
        response = self._get_request(
            f"{self.api_url}/v1/team/token-usage",
            _headers
        )

        if response.status_code == 200:
            try:
                response_json = response.json()
                if response_json.get('success') and 'data' in response_json:
                    return V1TokenUsageResponse(**response_json)
                elif "error" in response_json:
                    raise Exception(f"Failed to get token usage. Error: {response_json['error']}")
                else:
                    raise Exception(f"Failed to get token usage. Error: {response_json}")
            except ValueError:
                raise Exception('Failed to parse Firecrawl response as JSON.')
        else:
            self._handle_error(response, 'get token usage')

    def get_credit_usage_historical(self, by_api_key: bool = False) -> V1CreditUsageHistoricalResponse:
        """Get historical credit usage (v1)."""
        _headers = self._prepare_headers()
        url = f"{self.api_url}/v1/team/credit-usage/historical" + ("?byApiKey=true" if by_api_key else "")
        response = self._get_request(url, _headers)

        if response.status_code == 200:
            try:
                response_json = response.json()
                if response_json.get('success') and 'periods' in response_json:
                    return V1CreditUsageHistoricalResponse(**response_json)
                elif "error" in response_json:
                    raise Exception(f"Failed to get historical credit usage. Error: {response_json['error']}")

View on GitHub (pinned to 656bffcc28)

Solutions

  1. Upgrade firecrawl-py to the latest release.
  2. Print str(e) to inspect the unexpected response_json.
  3. Remove any transforming proxy.
  4. Pin to a compatible SDK version if needed.

Example fix

// before
usage = app.get_token_usage()

// after
try:
    usage = app.get_token_usage()
except Exception as e:
    print("unexpected token-usage body:", str(e))
    raise
Defensive patterns

Strategy: try-catch

Validate before calling

import firecrawl
assert hasattr(firecrawl, '__version__'), 'pin SDK version'

Type guard

def is_expected_usage_shape(d: dict) -> bool:
    return d.get('success') is True and 'data' in d

Try / catch

try:
    usage = app.get_token_usage()
except Exception as e:
    if 'Failed to get token usage. Error:' in str(e) and '{' in str(e):
        log.error('token-usage schema drift: %s', str(e))
    raise

Prevention

When it happens

Trigger: SDK/server version mismatch; proxy returning a non-conforming body for the token-usage endpoint.

Common situations: Outdated SDK against newer cloud API; intermediary gateway rewriting the response.

Related errors

AI-assisted analysis of firecrawl/firecrawl@656bffcc28 (2026-08-12). Data as JSON: /api/errors/ea9eda844b42f40c. Report an issue: GitHub.