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
| Outcome | Billed |
|---|---|
Computed 200 | Yes, one call |
Deterministic decline 200 | Yes, one call |
Reconcile 200 (any status) | Yes, one call |
| What-if and review-packet | One call per scenario that computed or declined |
Any 4xx or 5xx | No |
| Idempotent replay (same key, same body) | No; the original call was the one billed |
GET discovery and the capability manifest | No |
“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
| Plan | Calls per month | Requests per minute | API keys |
|---|---|---|---|
| free | 250 | 10 | 1 |
| developer | 2,500 | 60 | 2 |
| startup | 20,000 | 120 | 5 |
| scale | 150,000 | 300 | 10 |
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/reconcileyou get the original response byte for byte, with the headerIdempotent-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.
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
Monthly quota
When the account has used its monthly calls, every compute returns
429witherror: "quota_exceeded"andnext_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.Per-minute rate
Above your plan's requests per minute, calls return
429witherror: "rate_limit_exceeded"andretry_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:
| Header | Meaning |
|---|---|
| X-Quota-Limit / X-Quota-Remaining | Monthly calls on the plan, and calls left (shared across your keys) |
| X-RateLimit-Limit / X-RateLimit-Remaining | Requests allowed per minute, and requests left this minute |
| Idempotent-Replayed | true 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.
| Capability | Status |
|---|---|
| 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 |
| Capability | Status |
|---|---|
| Pricing + billing semantics (usage-based, no overage)Usage-based pricing and billing, with no overage charges. | ✅ shipped & certified |