docs(troubleshoot): cost discrepancy debugging guide

[Sameerlite]

Summary

Adds a troubleshooting guide and blog post for reconciling LiteLLM spend vs provider bills: align time ranges, compare token categories (including cache semantics), branch on ~10% deltas (ingestion vs pricing), and escalation via GitHub issue with LiteLLM scheduling a live call when needed.

Changes

• New doc: docs/troubleshoot/cost_discrepancy.md (sidebar under Troubleshooting)
• New blog: blog/debug_cost_discrepancy
• Screenshots in static/img/cost-discrepancy-debug/
• Callout + link from docs/proxy/cost_tracking.md
• Flowchart SVG: Path B connectors drawn below the box to avoid covering text

Testing

• npm run build in docs/my-website (docs-only; no Python tests).

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
litellm	Ready	Preview, Comment	Apr 15, 2026 4:07pm

[codspeed-hq]

Merging this PR will not alter performance

✅ 16 untouched benchmarks

---

_{Comparing Sameerlite:litellm_docs_cost_discrepancy_guide (3fdd67f) with main (72a461b)}

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[greptile-apps]

Greptile Summary

This PR adds a step-by-step troubleshooting guide for cost discrepancies between LiteLLM and provider bills (docs/troubleshoot/cost_discrepancy.md), wires it into the sidebar under Troubleshooting, and adds an :::info callout linking to it from docs/proxy/cost_tracking.md. The guide covers time-range alignment, traffic verification, per-category token comparison, and branching resolution paths (token ingestion vs. formula vs. model-map pricing). Note: the PR description still mentions a blog post (blog/debug_cost_discrepancy) that was deleted in the final commit, so that description is now stale.

Confidence Score: 5/5

Safe to merge — docs-only addition with correct sidebar wiring, valid relative links, and two minor P2 grammar suggestions.

All changed files are documentation. Sidebar entry, cross-doc links, and the callout in cost_tracking.md are all correctly formed. No code paths, migrations, or tests are affected. The only findings are P2 editorial nits in the new doc.

No files require special attention.

Important Files Changed

Filename	Overview
docs/my-website/docs/troubleshoot/cost_discrepancy.md	New troubleshooting guide — well-structured with a clear 4-step workflow, inline SVG flowchart, and escalation path; two minor text issues (grammar nit in SVG label, ambiguous "treating" phrasing)
docs/my-website/docs/proxy/cost_tracking.md	Adds a single :::info callout linking to the new cost_discrepancy guide; relative path resolves correctly from docs/proxy/
docs/my-website/sidebars.js	Adds "troubleshoot/cost_discrepancy" as the second entry in the Troubleshooting category — placement and ID are correct

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[Compare provider vs LiteLLM\nfor selected time range] --> B{Any category off\nby > 10%?\nrequests / input / output / cache}
    B -- YES --> C[Path A: Token ingestion issue]
    B -- NO --> D[Path B: Quantities match,\ncost differs]
    C --> E[Report to LiteLLM team\nscreenshots + endpoints + model names]
    D --> F[B1: Fix formula\nmanual cost calculation]
    D --> G[B2: Fix model map\ncheck model_prices_and_context_window.json]
    E & F & G --> H{Still unresolved?}
    H --> I[Open GitHub issue\nwith Step 3 comparison table]

Loading

_{Reviews (3): Last reviewed commit: "Delete docs/my-website/blog/debug_cost_d..." | Re-trigger Greptile}

[ishaan-berri]

No need for a blog post here