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
200response withcomputed: false, acode, and areason. 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_safeisfalseandnext_actionisreview_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:
- 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.
- 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.
- Tell us if many of your cases hit the same code: Ask for missing coverage.
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
}'{
"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"
}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
}'{
"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.
| Code | At minimum, a preparer handles |
|---|---|
year_not_modeled | a 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_income | a 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_review | a 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_review | a 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_review | a 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_wages | a 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_review | a 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_review | a preparer must confirm the qualifying-child / other-dependent eligibility for the Child Tax Credit. |
premium_tax_credit_needs_review | a preparer must complete Form 8962, including any excess advance premium tax credit repayment. |
engine_declined | a 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.
| Capability | Status |
|---|---|
| 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 |