Using the API

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:

FieldMeaning
computedtrue: the figures are the answer. false: a deterministic decline; code and reason say why. (Reconcile uses status instead.)
billedWhether 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_safeWhether 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_actionWhat 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.
reasonHuman-readable explanation of a decline or error. Show it; don't parse it.
provenanceOn successful computes only: the deterministic engine, jurisdiction, and tax year.

Every state a call can end in

StateBilledretry_safenext_actionWhat to do
ComputedHTTP 200computed: trueYestruenoneUse the figures. Show the line derivations (where a line has one) and the legal notice alongside them.
Deterministic declineHTTP 200computed: false + codeYesfalsereview_inputsA final answer, not an error. Show the reason and route the case to a preparer. The same body declines again.
Reconcile resultHTTP 200status: match | mismatch | unsupported | needs_reviewYestruereview_inputsnext_action is none only for match. Anything else goes to a person, who resolves the diff rows.
Validation errorHTTP 400error + issues[]Nofalsefix_request_and_resubmitFix 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 errorHTTP 401 / 403error: unauthorized | account_suspendedNofalsecheck_credentials401: the key is missing, unknown, or revoked. 403: the account is suspended; contact support.
Monthly quota reachedHTTP 429error: quota_exceededNofalseupgrade_plan_or_wait_next_periodA hard cap with no overage charge. Upgrade to a larger plan or wait for the next calendar month (UTC).
Rate limitHTTP 429error: rate_limit_exceededNotrueretry_after_backoffThe 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 replayHTTP same as the originalheader Idempotent-Replayed: true (single-compute endpoints and reconcile)Once in total—same as the originalYou receive the original response byte for byte. Nothing new was billed.
Idempotency key reusedHTTP 409error: idempotency_key_reusedNofalseuse_new_idempotency_keyA client bug: the same key was sent with a different body. Use a new key for a new request.
Idempotency in progressHTTP 409error: idempotency_key_in_progressNotrueretry_after_inflight_completesThe first request with this key is still running. Wait a moment and retry with the same key.
Server errorHTTP 500error: internal error …Nofalsefix_request_and_resubmitOur bug, not yours. Email support with the endpoint and time. Do not show a tax figure.
Metering unavailableHTTP 503error: metering_failureNotrueretry_after_backoffTemporary. 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):

Request
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
  }'
Response 200 · COMPUTED
{
  "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:

FieldDescription
computedbooleanAccepted by the API; not yet described in the OpenAPI spec.
billedbooleanAccepted by the API; not yet described in the OpenAPI spec.
retry_safebooleanAccepted 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: 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

provenanceobjectDeterministic derivation basis; present on successful computed/workflow responses only.
yearintegerTax year computed (computed:true).
filingStatusstringFiling status computed (computed:true).
taxableIncomeintegerLine 15 — taxable income, whole dollars (computed:true).
incomeTaxintegerLine 16 — income tax before other taxes/credits (computed:true).
totalTaxintegerLine 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).

premiumTaxCreditobjectForm 8962; present iff it computed.
additionalChildTaxCreditintegerRefundable 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)).
endingCapLossCarryoverSTintegerSchedule D SHORT-term capital-loss carryover to NEXT year (positive magnitude). Present only when non-zero. Feed back as next year's priorYearCapLossCarryoverST.
endingCapLossCarryoverLTintegerSchedule D LONG-term capital-loss carryover to NEXT year (positive magnitude). Present only when non-zero. Feed back as next year's priorYearCapLossCarryoverLT.
endingInvestmentInterestCarryforwardintegerForm 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 objectPer-line breakdown (computed:true); each carries its own primary-source derivation.
flagsarray of stringAdvisory engine flags (non-authoritative notes).
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: year_not_modeled, special_rate_gain_unmodeled, capital_loss_carryover_amt_difference_unmodeled, estate_trust_amt_adjustment_unmodeled, k1_needs_review, dependent_filer_needs_review, out_of_scope_income, surtax_additional_medicare, itemized_deduction_needs_review, foreign_tax_credit_needs_review, capital_gain_lots_need_review, equity_comp_basis_adjustment_needs_review, section_1256_needs_review, digital_asset_needs_review, schedule_c_needs_review, schedule_c_loss_needs_review, schedule_c_se_needs_social_security_wages, schedule_e_needs_review, pension_needs_review, social_security_needs_review, child_tax_credit_needs_review, premium_tax_credit_needs_review, engine_declined

reasonstringDecline/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.

Request
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
  }'
Response 200 · DECLINED · year_not_modeled
{
  "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.

FieldDescription
errorstringAccepted by the API; not yet described in the OpenAPI spec.
billedfalseAccepted by the API; not yet described in the OpenAPI spec.
retry_safebooleanAccepted 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: 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

reasonstringAccepted by the API; not yet described in the OpenAPI spec.

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.

Special federal taxes & safe-decline mechanics
CapabilityStatus
Provenance / derivation trace (faithfulness-gated)Provides a provenance and derivation trace of how results were reached, gated for faithfulness.✅ shipped & certified
Product-builder API, contract & trust surfaces
CapabilityStatus
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
Commercial, legal, docs, onboarding
CapabilityStatus