Using the API

Declines & affirmations

When a case falls outside what the engine models, or a fact it needs has not been attested, it returns a deterministic decline instead of a number. This page explains how to read one and how to resolve it.

What a decline is

  • A 200 response with computed: false, a code, and a reason. It is a final, correct answer, not an error and not an outage.
  • It is deterministic: the same body declines the same way every time, so retry_safe is false and next_action is review_inputs.
  • It is billed like a computed answer, because the engine did the work of checking the case.
  • It never contains a partial or estimated tax figure. Do not show one in its place.
  • It can only name what the request shows. The engine cannot detect income or facts that were left out of the request.

How to resolve one

Read the reason: it names the case-specific forms, thresholds, or fields involved. Then do one of three things:

  1. Supply a missing fact or affirmation, if the reason names one and a preparer can attest to it. The quickstart shows a Schedule C decline resolved this way.
  2. Route the case to a preparer, if the reason describes a surface the engine does not model. The table below lists, at minimum, what they will need to handle.
  3. Tell us if many of your cases hit the same code: Ask for missing coverage.
Interest income without the estate/trust K-1 affirmation declines, and the reason names the field:
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": 90000,
    "medicareWages": 90000,
    "taxableInterest": 1200
  }'
Response 200 · DECLINED · estate_trust_amt_adjustment_unmodeled
{
  "computed": false,
  "code": "estate_trust_amt_adjustment_unmodeled",
  "reason": "this return carries investment income (taxableInterest), which requires estateTrustK1NoAmtAdjustmentAffirmed:true. It attests that no Schedule K-1 (Form 1041) received for this tax year, from any estate or trust, shows a positive amount in box 12 code A (adjustment for minimum tax purposes, Form 6251 line 2j) or any amount, positive or negative, in box 12 codes B through I. Attest true if no such K-1 was received, or if every code A amount is zero or negative and codes B through I are blank on all of them (a negative code A left out over-states the tax). This engine sets Form 6251 line 2j to $0; if a K-1 does carry such an amount, a preparer must complete Form 6251.",
  "billed": true,
  "retry_safe": false,
  "next_action": "review_inputs"
}
Full response, including line derivations
{
  "computed": false,
  "code": "estate_trust_amt_adjustment_unmodeled",
  "reason": "this return carries investment income (taxableInterest), which requires estateTrustK1NoAmtAdjustmentAffirmed:true. It attests that no Schedule K-1 (Form 1041) received for this tax year, from any estate or trust, shows a positive amount in box 12 code A (adjustment for minimum tax purposes, Form 6251 line 2j) or any amount, positive or negative, in box 12 codes B through I. Attest true if no such K-1 was received, or if every code A amount is zero or negative and codes B through I are blank on all of them (a negative code A left out over-states the tax). This engine sets Form 6251 line 2j to $0; if a K-1 does carry such an amount, a preparer must complete Form 6251.",
  "billed": true,
  "retry_safe": false,
  "next_action": "review_inputs"
}
With the affirmation (and a preparer who has checked it), the same facts compute:
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": 90000,
    "medicareWages": 90000,
    "taxableInterest": 1200,
    "ordinaryDividends": 4000,
    "qualifiedDividends": 4000,
    "estateTrustK1NoAmtAdjustmentAffirmed": true
  }'
Response 200 · COMPUTED
{
  "computed": true,
  "year": 2025,
  "filingStatus": "single",
  "taxableIncome": 79450,
  "incomeTax": 12119,
  "totalTax": 12119,
  "lines": [
    { "lineId": "1040:15", "label": "Taxable income", "amount": 79450 },
    {
      "lineId": "1040:16",
      "label": "Income tax",
      "amount": 12119,
      "derivation": "<7 derivation steps — see full response>"
    },
    { "lineId": "1040:24", "label": "Total tax", "amount": 12119 }
  ],
  "flags": [
    "OBBBA-2025-new-deductions-senior-bonus/tips/overtime/car-loan-NOT-evaluated-engine-cannot-verify-eligibility-from-W2/1099-preparer-must-confirm"
  ],
  "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": 79450,
  "incomeTax": 12119,
  "totalTax": 12119,
  "lines": [
    {
      "lineId": "1040:15",
      "label": "Taxable income",
      "amount": 79450,
      "derivation": []
    },
    {
      "lineId": "1040:16",
      "label": "Income tax",
      "amount": 12119,
      "derivation": [
        {
          "lineId": "1040:16",
          "label": "Tax Table method (IRS-mandated below $100,000 taxable income)",
          "inputs": [
            { "name": "taxableIncome", "value": 75450 }
          ],
          "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 $75,450 → Tax Table band midpoint $75,475",
          "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": 27000 }
          ],
          "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 × $27,000 = $5,940",
          "result": 5940
        },
        {
          "lineId": "1040:16",
          "label": "Whole-dollar rounding — ordinary income tax",
          "inputs": [
            { "name": "unroundedOrdinaryTax", "value": 11519 }
          ],
          "rule": {
            "description": "round the ordinary income tax to whole dollars",
            "authority": "Form 1040 instructions — whole-dollar rounding"
          },
          "computation": "$11,519 − $11,518.5 = $0.5",
          "result": 0.5
        },
        {
          "lineId": "1040:16",
          "label": "Long-term gain / qualified dividends — 15% rate layer",
          "inputs": [
            { "name": "preferentialIncomeAt15", "value": 4000 }
          ],
          "rule": {
            "description": "15% preferential rate within the 15% band",
            "authority": "IRC §1(h)",
            "constantRef": {
              "table": "LTCG_BY_YEAR",
              "key": "2025/single",
              "value": "15% from $48,350 to $533,400 taxable income",
              "revProc": "Rev. Proc. 2024-40"
            }
          },
          "computation": "0.15 × $4,000 = $600, rounded to $600 (QDCGT line 18)",
          "result": 600
        },
        {
          "lineId": "1040:16",
          "label": "QDCGT Worksheet line 25 — smaller of line 23 or line 24",
          "inputs": [
            { "name": "line23StackedTax", "value": 12119 },
            { "name": "line24AllOrdinaryTax", "value": 12399 }
          ],
          "rule": {
            "description": "the taxpayer can never owe more than if none of the income received preferential treatment — line 25 is the smaller of the stacked (0/15/20-layered) computation and the all-ordinary computation on the full amount",
            "authority": "Form 1040 instructions — Qualified Dividends and Capital Gain Tax Worksheet, line 25"
          },
          "computation": "min($12,119, $12,399) = $12,119 (selected line23)",
          "result": 0
        }
      ]
    },
    {
      "lineId": "1040:24",
      "label": "Total tax",
      "amount": 12119,
      "derivation": []
    }
  ],
  "flags": [
    "OBBBA-2025-new-deductions-senior-bonus/tips/overtime/car-loan-NOT-evaluated-engine-cannot-verify-eligibility-from-W2/1099-preparer-must-confirm"
  ],
  "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."
  }
}

Federal decline codes

These are every code the federal engine can return, read from the capability manifest. The second column is the manifest's non-exhaustive routing note; the reason on the actual response is always more specific.

CodeAt minimum, a preparer handles
year_not_modeleda preparer must prepare this return for a tax year the engine does not model.
special_rate_gain_unmodeled
a preparer must apply the §1250 unrecaptured-gain and §1202 exclusion special rates via the Schedule D tax worksheet for a year the engine does not model them,…

a preparer must apply the §1250 unrecaptured-gain and §1202 exclusion special rates via the Schedule D tax worksheet for a year the engine does not model them, or complete Form 6251 Part III by hand when an AMT-side Schedule D difference (e.g. a Schedule K-1, Form 1041, box 12 code B-F) is present.

capital_loss_carryover_amt_difference_unmodeled
a preparer must complete Form 6251 Part III (and, if applicable, an AMT-side Schedule D Tax Worksheet) by hand when a prior-year capital-los…

a preparer must complete Form 6251 Part III (and, if applicable, an AMT-side Schedule D Tax Worksheet) by hand when a prior-year capital-loss carryover's AMT-side amount differs from the regular-tax figure the engine was given.

estate_trust_amt_adjustment_unmodeled
a preparer must complete Form 6251 by hand, entering line 2j from Schedule K-1 (Form 1041) box 12 code A and any codes B through I where the…

a preparer must complete Form 6251 by hand, entering line 2j from Schedule K-1 (Form 1041) box 12 code A and any codes B through I where the instructions direct.

k1_needs_review
a preparer must enter the Schedule K-1 (Form 1041) items this engine does not compute (any box other than 1, 2a, 2b, 3 and 4a, or a K-1 with…

a preparer must enter the Schedule K-1 (Form 1041) items this engine does not compute (any box other than 1, 2a, 2b, 3 and 4a, or a K-1 with attached statements) on the return by hand.

dependent_filer_needs_review
a preparer must complete the return of a filer who can be claimed as a dependent: Form 8615 (kiddie tax) when unearned income exceeds the th…

a preparer must complete the return of a filer who can be claimed as a dependent: Form 8615 (kiddie tax) when unearned income exceeds the threshold, and any dependents or joint filing the engine does not model.

out_of_scope_incomea preparer must handle caller-asserted income or a §199A deduction the engine does not model, or income excluded on Form 2555, Form 4563 or under §933.
surtax_additional_medicare
a preparer must determine the Additional Medicare Tax when Medicare wages (box 5) are unavailable but the return shows other objective W-2 e…

a preparer must determine the Additional Medicare Tax when Medicare wages (box 5) are unavailable but the return shows other objective W-2 evidence (a positive box 1 wages, box 2 federal withholding, box 3 Social Security wages, or box 6 Medicare tax withheld).

itemized_deduction_needs_review
a preparer must review the itemized deduction…

a preparer must review the itemized deduction — the §63(c)(6)(A) married-filing-separately rule, the §163(h)(3) mortgage-interest limit, Form 4952 investment interest (including Form 8814 amounts), non-cash gifts (Form 8283), or Form 4684 disaster losses.

foreign_tax_credit_needs_review
a preparer must complete Form 1116 for the foreign tax credit…

a preparer must complete Form 1116 for the foreign tax credit — confirm the foreign tax withheld (1099-DIV box 7) is fully creditable (not treaty over-withheld, not blocked by the §901(k)/(l) holding-period rule) via foreignTaxIsFullyCreditableAffirmed, confirm the §904(j) de-minimis election (above that ceiling the engine always declines and the preparer completes Form 1116) — see compute-response.reason for which condition failed.

capital_gain_lots_need_reviewa preparer must reconcile the Form 8949 lots against the 1099-B basis, including any §1250 unrecaptured gain, §1256 contracts, or §1091 wash-sale adjustments.
equity_comp_basis_adjustment_needs_review
a preparer must adjust the equity-comp cost basis on Form 8949 against the 1099-B (missing affirmation/comp/dates/source-ref), or…

a preparer must adjust the equity-comp cost basis on Form 8949 against the 1099-B (missing affirmation/comp/dates/source-ref), or — for a QUALIFYING ISO disposition specifically — review the Form 6251 AMT preference (an AMT-side basis this engine does not model).

section_1256_needs_review
a preparer must complete Form 6781 for the §1256 contracts (reconciling the 1099-B box 11, or Schedule K-1 (Form 1065) box 11 code C for a p…

a preparer must complete Form 6781 for the §1256 contracts (reconciling the 1099-B box 11, or Schedule K-1 (Form 1065) box 11 code C for a partner's allocable share), or Form 4797 if the §475(f) mark-to-market election applies.

digital_asset_needs_reviewa preparer must review the digital-asset dispositions on Form 8949 / Form 1099-DA, and any ordinary-income treatment on Schedule 1, Schedule C, or Form 4797.
schedule_c_needs_review
a preparer must review the Schedule C net and its Schedule SE self-employment tax, or complete Form 6251 by hand when the net contains an AM…

a preparer must review the Schedule C net and its Schedule SE self-employment tax, or complete Form 6251 by hand when the net contains an AMT preference (depletion, circulation costs, long-term contracts, mining exploration/development costs, research/experimental costs, or intangible drilling costs).

schedule_c_loss_needs_reviewa preparer must apply the §465 at-risk, §469 passive-loss, and §183 hobby-loss limits to the Schedule C loss.
schedule_c_se_needs_social_security_wagesa preparer must compute the Schedule C net's Schedule SE tax with the taxpayer's W-2 Social Security wages (the §164(f) base is capped across W-2 + SE).
schedule_e_needs_review
a preparer must handle the Schedule E rental…

a preparer must handle the Schedule E rental — the §469 passive-loss limit on Form 8582, the §465 at-risk limit on Form 6198, any §199A QBI on Form 8995, and (for a full-disposition passive-loss release) any interaction with Form 6251 AMT.

pension_needs_reviewa preparer must determine the taxable pension amount from the 1099-R (and any Form 5329 early-distribution tax).
social_security_needs_review
a preparer must size the taxable Social Security under §86 using the 1099-INT / RRB-1099 and Form 1040 line 2a inputs, Form 8815 or adoption…

a preparer must size the taxable Social Security under §86 using the 1099-INT / RRB-1099 and Form 1040 line 2a inputs, Form 8815 or adoption-benefit exclusions (and Form 6251 where AMT interacts).

child_tax_credit_needs_reviewa preparer must confirm the qualifying-child / other-dependent eligibility for the Child Tax Credit.
premium_tax_credit_needs_reviewa preparer must complete Form 8962, including any excess advance premium tax credit repayment.
engine_declineda preparer must prepare this return; read the decline reason for the specific gap.

The state endpoint returns federal_declined when the federal return underneath the state return cannot be computed (its reason carries the federal explanation), and its own codes for state-specific boundaries. Reconcile reports boundaries through its status and per-line ENGINE-DECLINED rows.

Affirmations

An affirmation is a boolean field a preparer sets to true to attest to a fact the engine cannot verify from numbers alone. It unlocks one bounded path; without it, that path declines (some work the other way; each field's description says how). The capability manifest lists every one, in two groups (113 in all):

required_fields (20)

section1256CleanBrokerReportedAffirmed, section1256LossCurrentlyDeductibleAffirmed, section1256AggregateIsFinalNoAdjustmentOrDeferralAffirmed, section1256TaxpayerIsNotOptionsOrCommoditiesDealerAffirmed, section1256NotLimitedPartnerDealerEquityOptionAffirmed, cleanCoveredNoAdjustmentsAffirmed, scheduleERentalIsPassiveFinalNet, scheduleERentalNotSection162Business, stateIncomeConformsToFederal, itemizedDeductionsAreFinalStateAmount, ilNoAdditionsOrRecaptureAffirmed, ilFilingStatusMatchesFederalAffirmed, ncNoAdditionsAffirmed, ncFilingStatusMatchesFederalAffirmed, ncStandardDeductionAllowedAffirmed, miNoAdditionsAffirmed, miFilingStatusMatchesAffirmed, nhInterestDividendsTaxNotOwedAffirmed, tnHallTaxNotOwedAffirmed, waCapitalGainsExciseNotOwedAffirmed

additional_fields (93), including the investment-income and Schedule C ones the guides use

scheduleERentalActiveParticipationAffirmed, scheduleERentalNoPriorSuspendedPALAffirmed, scheduleERentalAtRiskAffirmed, scheduleERentalNotRealEstateProfessionalAffirmed, scheduleERentalEntireInterestDisposedAffirmed, scheduleERentalFullyTaxableCashSaleAffirmed, scheduleERentalUnrelatedPartyAffirmed, scheduleERentalDispositionAtRiskAffirmed, scheduleERentalDispositionGainReflectedAffirmed, scheduleERentalNoAmtDifferenceAffirmed, scheduleCIsSingleSolePropFinalNetAffirmed, scheduleCNoAmtAdjustmentAffirmed, scheduleCPersonalServicesCapitalNotMaterialAffirmed, pensionDistributionFullyTaxableAffirmed, pensionDistributionNotSubjectToEarlyWithdrawalPenaltyAffirmed, pensionDistributionNonqualifiedAnnuityEarlyWithdrawalBasisIsValidUnder72qAffirmed, pensionDistributionEarlyWithdrawalBasisIsAvailableForThisPlanTypeAffirmed, pensionDistributionNoSeppModificationRecaptureAffirmed, pensionDistributionIsNonqualifiedAnnuityNii, mortgageInterestExcludesExcessRefinancingProceeds, socialSecurityStandardCaseAffirmed, childTaxCreditChildrenQualifyAffirmed, ctcActcFilerAndSpouseValidSsnAffirmed, federalPublicBenefitAffirmed, otherDependentsQualifyForOdcAffirmed, odcFilerAndSpouseValidTinAffirmed, caUsObligationInterestAffirmed, caScheduleCSelfEmployedForCaPurposesAffirmed, nyScheduleCNoStateBusinessAdjustmentsAffirmed, caScheduleCNoStateBusinessAdjustmentsAffirmed, caOutOfStateMuniInterestAffirmed, caUsObligationRicDividendAffirmed, caHsaAddbacksAffirmed, nyScheduleENoStateBusinessAdjustmentsAffirmed, caPensionIsUniformedServicesRetiredPayOrDodSbpAffirmed, caPensionNoEarlyDistributionAdditionalTaxAffirmed, caNoIraToHsaFundingDistributionAffirmed, equityCompBasisIsCompAdjustedAffirmed, washSaleDisallowedIsCompleteAffirmed, washSaleLotsNotSpecialRateAffirmed, washLotIsSingleAcquisitionBlockAffirmed, washLotIsCombinedMultiBlockAffirmed, equityCompIsoDisqualifyingDispositionAffirmed, foreignTaxNoCarryoverAffirmed, foreignSourceNoForm1116PartILines2Through5EntryAffirmed, foreignSourceNoForm1116Line16AdjustmentAffirmed, foreignTaxNoForm1116Line12ReductionAffirmed, foreignTaxIsFullyCreditableAffirmed, priorYearWasFull12MonthReturn, priorYearCitizenOrResidentAllYear, thisReturnWillBeFiledCovering12Months, sameSpouseAsThisReturn, foreignIncomeAllPassive1099, digitalAssetAllAcquiredByPurchase, digitalAssetNoneAreCollectible, digitalAssetIsCapitalNotOrdinary, taxExemptInterestNoPrivateActivityBonds, socialSecurityMfsLivedWithSpouse, spouseItemizesDeductions, canBeClaimedAsDependent, form8962Required, enteredPerForm8962InstructionsAffirmed, noForeignOrTerritoryExclusionAffirmed, seniorDeductionEligibilityAffirmed, scheduleCQbiEligible, medicalExpensesQualifyingUnreimbursedAffirmed, medicalExpensesNotCompensatedOtherwiseAffirmed, charitableCashToPublicCharitiesSubstantiatedAffirmed, charitableNoOtherContributionsOrCarryoverAffirmed, charitableNonCashNotAppreciatedAffirmed, charitableNonCashPublicSecuritiesAffirmed, charitableContributionsCompleteAffirmed, gamblingWinningsGrossAndLossesSubstantiatedAffirmed, investmentInterestQualifiesAffirmed, qualifiedDisasterCasualtyAffirmed, nyPrivatePensionQualifiesFor20kExclusion, nyPensionIsGovernmentPension, nyGovernmentPensionNotOrpOrEntirelySunyCunyNysedAttributableAffirmed, nyNqdcPensionWagesAmount, nyNqdcPensionQualifiesFor20kExclusionAffirmed, nyPrivatePensionIsEntirelyRecipientsOwnNotInheritedAffirmed, mortgageInterestSecuresAmtQualifiedDwelling, mortgageInterestSecuresSec121PrincipalResidence, collectibles28NoSec1202ExclusionPreferenceAffirmed, specialRateGainNoAmtScheduleDDifferenceAffirmed, capLossCarryoverNoAmtDifferenceAffirmed, estateTrustK1NoAmtAdjustmentAffirmed, k1AmountsNotReportedElsewhereAffirmed, otherBoxesBlankAffirmed, ilPensionIsQualifiedRetirementIncomeAffirmed, miCapitalGainsSameForMichiganAffirmed, miNoRetirementOrAgeDeductionsAffirmed, miRetirementFactsAffirmed

Each field's exact attestation is in its description in the federal reference and the state reference.

Never affirm to make a decline go away

Setting an affirmation to true is a statement that the fact is true for this return. If no one has checked it, route the case to a preparer instead. A wrong affirmation produces a confident wrong number, which is exactly what the decline was protecting against.

See also: Show declines in your product.

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
Deterministic-or-DECLINE doctrine (no runtime LLM)The engine is deterministic: it either computes a result or declines, and runs no LLM at runtime.✅ shipped & certified