Using the API

Billing, retries & limits

What counts as a billed call, how to retry without paying twice, and what happens at your plan's limits.

What is billed

OutcomeBilled
Computed 200Yes, one call
Deterministic decline 200Yes, one call
Reconcile 200 (any status)Yes, one call
What-if and review-packetOne call per scenario that computed or declined
Any 4xx or 5xxNo
Idempotent replay (same key, same body)No; the original call was the one billed
GET discovery and the capability manifestNo

“Billed” means the call counts toward your plan's monthly allowance. Every response's billed field tells you which happened. Calls through the MCP transport are currently not metered.

Plan limits

PlanCalls per monthRequests per minuteAPI keys
free250101
developer2,500602
startup20,0001205
scale150,00030010

Limits apply to the account, shared across its keys. Prices are on Pricing.

Retry safely with an Idempotency-Key

Send a unique Idempotency-Key (a UUID) with each logical request. If the network fails and you do not know whether it arrived, send the same request again with the same key:

  • Same key, same body: on /federal, /state, and /reconcile you get the original response byte for byte, with the header Idempotent-Replayed: true. On what-if and review-packet, each scenario that already ran returns its original result. Either way nothing is billed twice.
  • Same key, different body: 409 idempotency_key_reused. That is a bug in the client; use a new key for a new request.
  • Same key while the first request is still running: 409 idempotency_key_in_progress. Wait a moment and retry with the same key.
  • Keys are scoped to your account and replay for 24 hours.
  • Errors are not stored, so retrying after a 4xx or 5xx is a fresh request.

The key is optional on /federal, /state, and /reconcile, and required on /what-if and /review-packet, which reject a request without one.

Every example in these docs sends a key
curl https://tax-mcp.com/api/mcp/tax-compute/federal \
  -H "Authorization: Bearer $TAX_MCP_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "year": 2025,
    "filingStatus": "single",
    "canBeClaimedAsDependent": false,
    "noForeignOrTerritoryExclusionAffirmed": true,
    "wages": 85000,
    "medicareWages": 85000,
    "federalWithholding": 9500
  }'

Never mint a new key to retry an unknown result

A new key makes it a new request, and if the first one did arrive you will be billed for both.

Quota and rate limits

  1. Monthly quota

    When the account has used its monthly calls, every compute returns 429 with error: "quota_exceeded" and next_action: "upgrade_plan_or_wait_next_period". It is a hard stop with no overage charge. Usage counts per calendar month (UTC) and starts again at zero on the 1st. Upgrading raises the cap at once without resetting usage, so calls resume if you are below the new plan's limit.

  2. Per-minute rate

    Above your plan's requests per minute, calls return 429 with error: "rate_limit_exceeded" and retry_safe: true. The limit counts requests per UTC calendar minute across all of the account's keys, so wait for the next minute and retry. What-if and review-packet count each scenario against the rate.

Usage headers

Successful /federal, /state, and /reconcile responses report your usage, so you can slow down before a limit:

HeaderMeaning
X-Quota-Limit / X-Quota-RemainingMonthly calls on the plan, and calls left (shared across your keys)
X-RateLimit-Limit / X-RateLimit-RemainingRequests allowed per minute, and requests left this minute
Idempotent-Replayedtrue when the response is a replay of an earlier request with the same key

Your live usage is also on the dashboard. For persistent 500 or 503 responses, email support@tax-mcp.com with the endpoint and time (never the key or the body).

See also: Reference overview.

Roadmap status for this page

Generated from the roadmap (updated 2026-10-30). Shipped & certified means live and independently checked against primary tax sources; certifying means live, with those checks still in progress.

Product-builder API, contract & trust surfaces
CapabilityStatus
Idempotency (byte-identical replay, bills-once); quota & rate (hard-429)Replays repeated requests byte-identically and bills them once; quota and rate limits return a hard HTTP 429.✅ shipped & certified
Commercial, legal, docs, onboarding
CapabilityStatus
Pricing + billing semantics (usage-based, no overage)Usage-based pricing and billing, with no overage charges.✅ shipped & certified