Responses & states
Every response, success or error, carries the same contract fields, so one piece of client code can decide what to do next without parsing tax figures.
Read the envelope first
Branch on these fields before you look at any amount:
| Field | Meaning |
|---|---|
| computed | true: the figures are the answer. false: a deterministic decline; code and reason say why. (Reconcile uses status instead.) |
| billed | Whether this call counted toward your plan. It is the ledger's truth for this response, not a guess from the status code. Errors are always false. |
| retry_safe | Whether it is worth sending this exact request again (same body, same Idempotency-Key), now or after a backoff. It never means “mint a new key and try again”. |
| next_action | What your code should do next. One of none, review_inputs, fix_request_and_resubmit, check_credentials, upgrade_plan_or_wait_next_period, retry_after_backoff, retry_after_inflight_completes, use_new_idempotency_key. |
| reason | Human-readable explanation of a decline or error. Show it; don't parse it. |
| provenance | On successful computes only: the deterministic engine, jurisdiction, and tax year. |
Every state a call can end in
| State | Billed | retry_safe | next_action | What to do |
|---|---|---|---|---|
Computedcomputed: true | Yes | true | none | Use the figures. Show the line derivations (where a line has one) and the legal notice alongside them. |
Deterministic declinecomputed: false + code | Yes | false | review_inputs | A final answer, not an error. Show the reason and route the case to a preparer. The same body declines again. |
Reconcile resultstatus: match | mismatch | unsupported | needs_review | Yes | true | review_inputs | next_action is none only for match. Anything else goes to a person, who resolves the diff rows. |
Validation errorerror + issues[] | No | false | fix_request_and_resubmit | Fix the request and send again. issues[].path names the field where it can; unrecognized_keys means a field name the API does not accept. |
Auth errorerror: unauthorized | account_suspended | No | false | check_credentials | 401: the key is missing, unknown, or revoked. 403: the account is suspended; contact support. |
Monthly quota reachederror: quota_exceeded | No | false | upgrade_plan_or_wait_next_period | A hard cap with no overage charge. Upgrade to a larger plan or wait for the next calendar month (UTC). |
Rate limiterror: rate_limit_exceeded | No | true | retry_after_backoff | The limit is per UTC calendar minute, shared by all of the account's keys. Wait for the next minute and retry the same request. |
Idempotent replayheader Idempotent-Replayed: true (single-compute endpoints and reconcile) | Once in total | — | same as the original | You receive the original response byte for byte. Nothing new was billed. |
Idempotency key reusederror: idempotency_key_reused | No | false | use_new_idempotency_key | A client bug: the same key was sent with a different body. Use a new key for a new request. |
Idempotency in progresserror: idempotency_key_in_progress | No | true | retry_after_inflight_completes | The first request with this key is still running. Wait a moment and retry with the same key. |
Server errorerror: internal error … | No | false | fix_request_and_resubmit | Our bug, not yours. Email support with the endpoint and time. Do not show a tax figure. |
Metering unavailableerror: metering_failure | No | true | retry_after_backoff | Temporary. Retry with the same Idempotency-Key after a short backoff. The call is never served unbilled. |
Billed means the call counted as one of your plan's monthly calls. What-if and review-packet count each scenario separately. See Billing, retries & limits.
The computed result
A computed federal response looks like this (each line's derivation is collapsed; open the full response to see it):
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
}'{
"computed": true,
"year": 2025,
"filingStatus": "single",
"taxableIncome": 69250,
"incomeTax": 10155,
"totalTax": 10155,
"lines": [
{ "lineId": "1040:15", "label": "Taxable income", "amount": 69250 },
{
"lineId": "1040:16",
"label": "Income tax",
"amount": 10155,
"derivation": "<5 derivation steps — see full response>"
},
{ "lineId": "1040:24", "label": "Total tax", "amount": 10155 }
],
"flags": [
"OBBBA-2025-new-deductions-senior-bonus/tips/overtime/car-loan-NOT-evaluated-engine-cannot-verify-eligibility-from-W2/1099-preparer-must-confirm"
],
"owedOrRefund": 655,
"billed": true,
"retry_safe": true,
"next_action": "none",
"provenance": { "engine": "deterministic", "jurisdiction": "federal", "tax_year": 2025 },
"legal_notice": {
"ref": "https://tax-mcp.com/terms#compute-notice",
"version": "v1",
"text": "<computation-support notice — see full response>"
}
}Full response, including line derivations
{
"computed": true,
"year": 2025,
"filingStatus": "single",
"taxableIncome": 69250,
"incomeTax": 10155,
"totalTax": 10155,
"lines": [
{
"lineId": "1040:15",
"label": "Taxable income",
"amount": 69250,
"derivation": []
},
{
"lineId": "1040:16",
"label": "Income tax",
"amount": 10155,
"derivation": [
{
"lineId": "1040:16",
"label": "Tax Table method (IRS-mandated below $100,000 taxable income)",
"inputs": [
{ "name": "taxableIncome", "value": 69250 }
],
"rule": {
"description": "Form 1040 instructions require the published Tax Table — a lookup on the midpoint of a narrow taxable-income band — for taxable income under $100,000; the exact bracket formula (Tax Computation Worksheet) applies only at $100,000 or more.",
"authority": "Form 1040 instructions — Tax Table"
},
"computation": "taxable income $69,250 → Tax Table band midpoint $69,275",
"result": 0
},
{
"lineId": "1040:16",
"label": "Ordinary income tax — 10% bracket",
"inputs": [
{ "name": "taxableIncomeInBracket", "value": 11925 }
],
"rule": {
"description": "marginal rate × taxable income falling within this bracket",
"authority": "IRC §1(j)",
"constantRef": {
"table": "BRACKETS_BY_YEAR",
"key": "2025/single",
"value": "10% (up to $11,925)",
"revProc": "Rev. Proc. 2024-40"
}
},
"computation": "0.1 × $11,925 = $1,192.5",
"result": 1192.5
},
{
"lineId": "1040:16",
"label": "Ordinary income tax — 12% bracket",
"inputs": [
{ "name": "taxableIncomeInBracket", "value": 36550 }
],
"rule": {
"description": "marginal rate × taxable income falling within this bracket",
"authority": "IRC §1(j)",
"constantRef": {
"table": "BRACKETS_BY_YEAR",
"key": "2025/single",
"value": "12% (up to $48,475)",
"revProc": "Rev. Proc. 2024-40"
}
},
"computation": "0.12 × $36,550 = $4,386",
"result": 4386
},
{
"lineId": "1040:16",
"label": "Ordinary income tax — 22% bracket",
"inputs": [
{ "name": "taxableIncomeInBracket", "value": 20800 }
],
"rule": {
"description": "marginal rate × taxable income falling within this bracket",
"authority": "IRC §1(j)",
"constantRef": {
"table": "BRACKETS_BY_YEAR",
"key": "2025/single",
"value": "22% (up to $103,350)",
"revProc": "Rev. Proc. 2024-40"
}
},
"computation": "0.22 × $20,800 = $4,576",
"result": 4576
},
{
"lineId": "1040:16",
"label": "Whole-dollar rounding — ordinary income tax",
"inputs": [
{ "name": "unroundedOrdinaryTax", "value": 10155 }
],
"rule": {
"description": "round the ordinary income tax to whole dollars",
"authority": "Form 1040 instructions — whole-dollar rounding"
},
"computation": "$10,155 − $10,154.5 = $0.5",
"result": 0.5
}
]
},
{
"lineId": "1040:24",
"label": "Total tax",
"amount": 10155,
"derivation": []
}
],
"flags": [
"OBBBA-2025-new-deductions-senior-bonus/tips/overtime/car-loan-NOT-evaluated-engine-cannot-verify-eligibility-from-W2/1099-preparer-must-confirm"
],
"owedOrRefund": 655,
"billed": true,
"retry_safe": true,
"next_action": "none",
"provenance": { "engine": "deterministic", "jurisdiction": "federal", "tax_year": 2025 },
"legal_notice": {
"ref": "https://tax-mcp.com/terms#compute-notice",
"version": "v1",
"text": "Computation support only. Not tax, legal, accounting, or financial advice. Customer is responsible for review, filing positions, and use only within the documented supported envelope."
}
}Every field a compute response can carry, from the OpenAPI spec:
| Field | Description |
|---|---|
| computedboolean | Accepted by the API; not yet described in the OpenAPI spec. |
| billedboolean | Accepted by the API; not yet described in the OpenAPI spec. |
| retry_safeboolean | Accepted by the API; not yet described in the OpenAPI spec. |
| next_actionenum (NextAction) | Stable machine-actionable next step (uniform across every response; same set in docs + live). Values: |
| provenanceobject | Deterministic derivation basis; present on successful computed/workflow responses only. |
| yearinteger | Tax year computed (computed:true). |
| filingStatusstring | Filing status computed (computed:true). |
| taxableIncomeinteger | Line 15 — taxable income, whole dollars (computed:true). |
| incomeTaxinteger | Line 16 — income tax before other taxes/credits (computed:true). |
| totalTaxinteger | Line 22/24 — total tax including NIIT/Additional-Medicare (computed:true). |
| owedOrRefundinteger | Owed (positive) or refund (negative);Owed (positive) or refund (negative); totalTax − withholding − ACTC − net premium tax credit (from 2026 it assumes Form 1040 line 32b is 0: see federalPublicBenefitAffirmed). Present when federalWithholding is supplied or a refundable credit is present (which can make it negative with no withholding). |
| premiumTaxCreditobject | Form 8962; present iff it computed. |
| additionalChildTaxCreditinteger | Refundable Additional Child Tax Credit (Schedule 8812 Part II → 1040 line 28); present only when > 0. Capped at min(unused CTC, qualifying-children × the year's refundable per-child cap, 15% × (W-2 wages − $2,500)). |
| endingCapLossCarryoverSTinteger | Schedule D SHORT-term capital-loss carryover to NEXT year (positive magnitude). Present only when non-zero. Feed back as next year's priorYearCapLossCarryoverST. |
| endingCapLossCarryoverLTinteger | Schedule D LONG-term capital-loss carryover to NEXT year (positive magnitude). Present only when non-zero. Feed back as next year's priorYearCapLossCarryoverLT. |
| endingInvestmentInterestCarryforwardinteger | Form 4952 line 7: investment interest disallowed this year, carried to next year whether or not the return itemizes. Present only when non-zero. Feed back as next year's investmentInterestCarryforward. |
| linesarray of object | Per-line breakdown (computed:true); each carries its own primary-source derivation. |
| flagsarray of string | Advisory engine flags (non-authoritative notes). |
| legal_noticeLegalNotice | Machine-readable not-tax-advice notice.Machine-readable not-tax-advice notice. Present on every `computed:true` compute 200 AND on every reconcile/workflow 200 regardless of status (match/mismatch/unsupported/needs_review); absent only from compute 200 declines (`computed:false`) and all non-200 responses. /terms governs ALL responses — including declines and errors — so this field is a per-success echo of /terms, and its absence never means the Terms don't apply. A stable constant — `version` changes only with the wording; `ref` points at the published /terms compute-notice. |
| equityCompDerivationarray of object | Present ONLY when an equity-comp (RSU/NSO/ISO-disqualifying/ESPP) lot computed:Present ONLY when an equity-comp (RSU/NSO/ISO-disqualifying/ESPP) lot computed: the ENGINE-DERIVED per-lot basis correction for §6694 auditability. Form 8949 code-B POSTURE / SIGN CONVENTION: col (e) keeps the broker-reported basis (roundedReportedBasis), col (f) = code B, col (g) = basisAdjustmentAmount (NEGATIVE — it reduces the gain; = roundedReportedBasis − derivedCorrectedBasis). derivedCorrectedBasis = round(reportedBasis + equityCompOrdinaryIncome) is the engine's INTERNAL basis operand, NOT a col-(e) entry — do not transcribe it into col (e) AND apply col (g) (double-count). Identities: gain = roundedProceeds − derivedCorrectedBasis = roundedProceeds − roundedReportedBasis + basisAdjustmentAmount. |
| amtDerivationobject | Form 6251 (AMT) proof-of-work trace.Form 6251 (AMT) proof-of-work trace. PRESENT iff AMT bound this year (amount > 0) — ABSENT means AMT did not bind ($0), the ONLY reason this field is omitted. Present regardless of whether the trace itself is status:computed or status:declined (Form 6251 Part III unrecaptured-§1250/28%-collectibles special-rate refiguration, or a failed faithfulness check, decline the trace while AMT is still charged in totalTax — a declined trace here does NOT mean AMT is $0). When status is computed: total is the AMT add-on (Form 6251 line 11, IRC §55(a)); steps trace AMTI (6251:4) -> exemption (6251:5) -> AMT base (6251:6) -> tentative minimum tax (6251:7) -> the add-on (6251:11). totalTax is NOT simply incomeTax + amtDerivation.total — it also includes any SE tax, NIIT, Additional-Medicare tax and excess advance premium tax credit repayment. |
| codeenum (DeclineCode) | Decline code (computed:false only). Values: |
| reasonstring | Decline/explanatory reason. |
Lines and derivations
lines lists the form lines the engine computed, each with a lineId (for example 1040:16), a label, and a whole-dollar amount. A federal line computed from a rule carries a derivation listing the steps: the inputs, the rule and its authority (an IRC section, a Revenue Procedure), and the arithmetic. Lines that only carry a total forward can have an empty one. State lines carry a cite to the source of the constant they use, where one applies.
Flags
flags are advisory notes, such as a deduction the engine could not evaluate from the facts given. They never change a figure. Show them to whoever reviews the return.
A decline
A decline is a 200 with computed: false. It carries no tax figures, no provenance, and no legal notice: only the code, the reason, and the contract fields.
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": 2019,
"filingStatus": "single",
"canBeClaimedAsDependent": false,
"noForeignOrTerritoryExclusionAffirmed": true,
"wages": 50000,
"medicareWages": 50000
}'{
"computed": false,
"code": "year_not_modeled",
"reason": "tax year 2019 is not modeled (supported: 2020, 2021, 2022, 2023, 2024, 2025, 2026)",
"billed": true,
"retry_safe": false,
"next_action": "review_inputs"
}Full response, including line derivations
{
"computed": false,
"code": "year_not_modeled",
"reason": "tax year 2019 is not modeled (supported: 2020, 2021, 2022, 2023, 2024, 2025, 2026)",
"billed": true,
"retry_safe": false,
"next_action": "review_inputs"
}Declines & affirmations lists every code and how to resolve each one.
Errors
Non-200 responses carry error as the machine-readable discriminator, plus the same contract fields. They are never billed.
| Field | Description |
|---|---|
| errorstring | Accepted by the API; not yet described in the OpenAPI spec. |
| billedfalse | Accepted by the API; not yet described in the OpenAPI spec. |
| retry_safeboolean | Accepted by the API; not yet described in the OpenAPI spec. |
| next_actionenum (NextAction) | Stable machine-actionable next step (uniform across every response; same set in docs + live). Values: |
| reasonstring | Accepted by the API; not yet described in the OpenAPI spec. |
The legal notice
Every computed 200 and every reconcile 200 carries legal_notice. Declines and errors do not, but the Terms govern every response either way.
{
"ref": "https://tax-mcp.com/terms#compute-notice",
"version": "v1",
"text": "Computation support only. Not tax, legal, accounting, or financial advice. Customer is responsible for review, filing positions, and use only within the documented supported envelope."
}Building the screens for these states?
Show declines in your product covers what to display for each one.
See also: Billing, retries & limits.
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 |
|---|---|
| Provenance / derivation trace (faithfulness-gated)Provides a provenance and derivation trace of how results were reached, gated for faithfulness. | ✅ shipped & certified |
| Capability | Status |
|---|---|
| Uniform response contract (billed / retry_safe / next_action / reason / provenance)Responses follow a uniform contract: billed, retry_safe, next_action, reason, and provenance. | ✅ shipped & certified |
| Capability | Status |
|---|---|
| Legal posture — /terms + legal_notice (customer-is-preparer, no E&O, 12-mo cap)Published terms: the customer is the preparer of record, no E&O insurance is represented, and liability is capped at 12 months of fees. | ✅ shipped & certified |