Troubleshooting TokenSense in n8n

Common errors and how to fix them. Each section includes the error, likely cause, and fix.

Install errors

ENOENT python / gyp ERR during install

Likely cause: Some dependencies require Python and native build tools (node-gyp) that aren't installed on your system.

Fix: Install python3 and build tools for your platform, then retry. On Debian/Ubuntu: apt-get install python3 build-essential. On macOS: xcode-select --install.

Node not appearing after install

Likely cause: n8n needs a restart to pick up newly installed community nodes.

Fix: Restart your n8n instance. On Docker: docker restart n8n. If using PM2: pm2 restart n8n. After restart, the TokenSense nodes should appear in the nodes panel.

Credential errors

401 Unauthorized

Likely cause: Invalid or expired API key.

Fix: Generate a new key at app.tokensense.io/keys and update your credential.

403 Forbidden

Likely cause: No provider API key configured for the model you requested (MISSING_PROVIDER_KEY), or a routing policy is blocking the request (POLICY_BLOCKED).

Fix: Check Settings → Providers in the dashboard to make sure the relevant provider key is added. If the error mentions a policy, check Settings → Routing Policies.

Network error / connection refused

Likely cause: Your n8n instance can't reach api.tokensense.io.

Fix: Check firewall rules, proxy settings, and DNS resolution. Test with: curl -I https://api.tokensense.io/health

Test works but workflows fail

Likely cause: The credential test is a lightweight check. Workflow failures usually mean a missing provider key (you need to add your OpenAI/Anthropic key in the TokenSense dashboard), model access issue, or budget exhaustion.

Fix: Check that you've added the relevant provider key in the dashboard under Provider Keys. Verify the model you're requesting is available on your provider account.

Runtime errors

400 — current model or endpoint mismatch

model_requires_responses_api: GPT 6.1 Sol and GPT 6 Astra tool requests require /v1/responses. Use an HTTP Request node with the Responses format, or select a Chat-compatible model for your AI Agent.

image_model_requires_native_endpoint: Gemini image output requires Image Generation or native generateContent, rather than Chat Completions. The Images compatibility route currently accepts one square 1K image.

model_retired: select a supported replacement and test it. Changing Imagen 4 to a Gemini image ID also requires the new request format. TokenSense preserves saved model IDs for history rather than silently changing your workflow.

For empty Claude text, increase the output limit: thinking can consume the token budget before visible text is produced. For Gemini 3.8 Flash, use low, medium, or high thinking and inspect the gateway's x-tokensense-adapted header for removed or mapped controls.

Empty or unavailable cost

Check pricingAvailable and billingReason for Image Generation, Speech-to-Text, and Text-to-Speech billing metadata in 0.1.20. Mini TTS can return valid audio with binary_audio_usage_unavailable; image responses can lack billable usage dimensions. Preserve this unknown state rather than replacing an empty cost with zero. See the node reference.

402 Payment Required

Your workflow budget is exhausted — exactly what you set it to do. TokenSense blocked the request because it would have exceeded your configured spend cap. Your workflow ran safely up to your limit; nothing went over.

Fix: Increase the relevant budget in your TokenSense project settings, or wait until the budget period resets. This is not an error — it's budget enforcement working as designed. See Budgets for how enforcement works.

429 Rate Limit

Likely cause: You're sending more requests per minute than your plan allows (Starter: 30/min, Pro: 120/min, Agency: 300/min). The Retry-After header tells you when to retry.

Fix: Add delays between requests in your workflow, reduce concurrency, or stagger execution times. Rate limits are per-workspace and reset every 60 seconds. Check the X-RateLimit-Remaining header to monitor usage proactively.

5xx Server Error

Likely cause: Temporary issue with TokenSense or the upstream provider.

Fix: Retry after a few seconds. If persistent, check [email protected]. Include the request timestamp and any error details from the n8n execution view.

Attribution issues

Wrong workflow tag in dashboard

Likely cause: The workflow name changed after the tag was set, or you have multiple nodes with different project tags in the same workflow.

Fix: Check the Project field on each TokenSense node in your workflow. Tags are set per-node, not per-workflow. Use consistent values.

Costs don't match dashboard

Likely cause: Cost calculation happens asynchronously. There may be a brief delay (usually <30 seconds) between execution and dashboard display.

Fix: Wait a moment and refresh. If costs are consistently wrong, check that your provider key is correctly configured and the model pricing is recognized. Contact support if discrepancies persist.

Where to get help