{"openapi":"3.1.0","info":{"title":"Tax MCP — Compute API","version":"1.0.0","description":"Deterministic, §6694-disciplined US tax-compute API. Federal (1040 / NIIT / Additional Medicare / AMT / OBBBA-SALT) and CA / NY / NYC state returns, plus a non-mutating reconcile. JSON in, computed (or honestly declined) tax out. Authenticate with a Bearer API key from your dashboard. Host: `https://tax-mcp.com` is the canonical direct host; call it directly. (A legacy `pliioai.com` proxy path forwarded to this same service and is being retired — new integrations should use `tax-mcp.com`.)"},"servers":[{"url":"https://tax-mcp.com","description":"Production (canonical direct host)"}],"security":[{"bearerAuth":[]}],"paths":{"/api/mcp/tax-compute/federal":{"post":{"summary":"Compute a federal 1040 return","operationId":"computeFederal","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FederalProfile"}}}},"responses":{"200":{"description":"Computed return (or an honest decline)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ComputeResult"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/AccountSuspended"},"409":{"$ref":"#/components/responses/IdempotencyConflict"},"429":{"$ref":"#/components/responses/QuotaOrRate"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"$ref":"#/components/responses/MeteringFailure"}}},"get":{"summary":"Federal capability / discovery (free — no quota charge)","operationId":"discoverFederal","responses":{"200":{"description":"Supported years + the full field list"},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/api/mcp/tax-compute/state":{"post":{"summary":"Compute a state return (CA or NY, discriminated by `state`)","operationId":"computeState","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StateProfile"}}}},"responses":{"200":{"description":"Computed return","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ComputeResult"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/AccountSuspended"},"409":{"$ref":"#/components/responses/IdempotencyConflict"},"429":{"$ref":"#/components/responses/QuotaOrRate"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"$ref":"#/components/responses/MeteringFailure"}}},"get":{"summary":"State capability / discovery (free)","operationId":"discoverState","responses":{"200":{"description":"Per-state (ca, ny) year + facts"},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/api/mcp/tax-compute/reconcile":{"post":{"summary":"Independently compute a CA 540 from source docs and reconcile vs a filed return","operationId":"reconcile","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object"}}}},"responses":{"200":{"description":"Reconciliation result (non-mutating; decline-aware)"},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/AccountSuspended"},"409":{"$ref":"#/components/responses/IdempotencyConflict"},"429":{"$ref":"#/components/responses/QuotaOrRate"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"$ref":"#/components/responses/MeteringFailure"}}},"get":{"summary":"Reconcile capability / discovery (free)","operationId":"discoverReconcile","responses":{"200":{"description":"Capability"}}}},"/api/mcp/tax-capabilities":{"get":{"summary":"Machine-readable supported-envelope discovery (public, no auth, no payloads)","operationId":"getTaxCapabilities","description":"Returns the supported envelope (jurisdictions, years, filing statuses, modeled income fields, out-of-scope list, decline codes, review states, uniform response fields, billing semantics, docs links) so a client can discover what is modeled vs declined WITHOUT sending taxpayer payloads or learning boundaries only from runtime declines.","responses":{"200":{"description":"Supported-envelope capability document"}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Your API key: `Authorization: Bearer taxmcp_…`"}},"parameters":{"IdempotencyKey":{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string"},"description":"Optional. A unique key per logical request (one key per operation). Retrying with the SAME key + SAME request body replays the byte-identical first response (with header `Idempotent-Replayed: true`) and bills exactly ONCE. The SAME key with a DIFFERENT body → 409 `idempotency_key_reused`. A concurrent in-flight duplicate → 409 `idempotency_key_in_progress` (retry). Keys are scoped per account and replay for 24h. Errors (4xx/5xx) are NOT cached — a retry after an error is a fresh request."}},"schemas":{"FederalProfile":{"type":"object","required":["year","filingStatus"],"description":"Supply at least one income field. Whole-dollar amounts; the engine applies the form's rounding.","properties":{"year":{"type":"integer","example":2025},"filingStatus":{"type":"string","enum":["single","married_filing_jointly","married_filing_separately","head_of_household"]},"wages":{"type":"number","description":"1040 line 1a — total W-2 box-1 wages"},"medicareWages":{"type":"number","description":"W-2 box-5 (≥ box-1) — the Additional Medicare Tax base"},"federalWithholding":{"type":"number","description":"W-2 box-2 federal income tax withheld — used for owed/refund"},"priorYearTax":{"type":"number","description":"Prior-year TOTAL TAX (Form 2210 line 8) — OPT-IN to the §6654 underpayment SAFE-HARBOR determination (iteration 40). When supplied, the response carries an underpaymentPenalty field that names the §6654(e)/(d) exemption zeroing the penalty (de-minimis / withholding ≥ required / prior-year-$0) OR status:needs_preparer (a penalty may be owed) — in which case an advisory penaltyCeiling (iteration 41) gives a conservative UPPER BOUND on the §6654 penalty (max-rate, full accrual to April 15, no estimated payments), guaranteed ≥ the true penalty and NOT a Form 1040 line-38 filed value; emitted only for a year with fully-published IRS rates. Separate line — does not change tax/AGI/refund. Federal-only."},"priorYearAGI":{"type":"number","description":"Prior-year AGI — selects the §6654(d)(1)(C)(i) safe-harbor percent (110% if > $150,000, or $75,000 MFS; else 100%). Absent → the engine assumes the high-income 110% (the larger-required, under-tax-safe direction)."},"priorYearWasFull12MonthReturn":{"type":"boolean","description":"§6654(d)(1)(C)(i): the prior-year safe harbor is available ONLY if the prior year was a filed 12-month return. Absent/false → the prior-year harbor does not apply and the required annual payment = 90% of current-year tax (the larger, under-tax-safe figure)."},"priorYearCitizenOrResidentAllYear":{"type":"boolean","description":"§6654(e)(2)(C): the prior-year-$0 penalty exception requires the taxpayer was a US CITIZEN or RESIDENT throughout the preceding year. A nonresident alien whose prior-year US tax was $0 because they were an NRA does NOT qualify; engine-invisible, so the (e)(2) exception is granted only when this is true (absent/false → not (e)(2))."},"taxableInterest":{"type":"number"},"ordinaryDividends":{"type":"number"},"qualifiedDividends":{"type":"number","description":"≤ ordinaryDividends — taxed at preferential LTCG/QDIV rates"},"reit199ADividends":{"type":"number","description":"1099-DIV box 5 — §199A REIT dividends (≤ ordinaryDividends). 20% QBI deduction (REIT box-5 ONLY; PTP/business QBI out of scope, declines)."},"scheduleCIncome":{"type":"number","description":"Schedule C line-31 net (sole-proprietor). A POSITIVE net COMPUTES self-employment tax (Schedule SE §1401/§1402: net×0.9235 → 12.4% OASDI to the $176,100 (2025) Social-Security wage base, coordinated with W-2 box-3 wages, then 2.9% Medicare uncapped) + the §164(f) one-half-SE-tax above-the-line deduction (reduces AGI), and the net flows to Schedule 1 line 3 → 1040 line 8 → AGI. REQUIRES scheduleCIsSingleSolePropFinalNetAffirmed:true; a LOSS → schedule_c_loss_needs_review; W-2 wages present without socialSecurityWages → schedule_c_se_needs_social_security_wages; QBI/§199A, depreciation/§179/bonus, multiple Schedule Cs, spouse allocation, SE health-insurance, home-office, farm/clergy/statutory, and §1402 optional methods are out of scope → schedule_c_needs_review. STATE: CA CONFORMS (iteration 39 — taxes the net in CA AGI as ordinary income; no CA SE tax / no CA §199A QBI), requiring BOTH caScheduleCSelfEmployedForCaPurposesAffirmed:true (AB5/ABC worker classification) AND caScheduleCNoStateBusinessAdjustmentsAffirmed:true (zero Schedule CA 540 line-3 business-income adjustment). NY ALSO CONFORMS (iteration 42 — taxes the net in NY AGI as ordinary income), requiring nyScheduleCNoStateBusinessAdjustmentsAffirmed:true (zero Form IT-225 §168(k)-bonus / 2025-R&E / §179-SUV business-income addition); NY needs NO worker-classification affirmation. A VERIFY flag names the separate NY MCTMT + NYC-UBT, which the engine does not compute."},"scheduleCIsSingleSolePropFinalNetAffirmed":{"type":"boolean","enum":[true],"description":"§6694 affirmation REQUIRED for a positive scheduleCIncome: attests it is the FINAL Schedule C line-31 net of ONE sole proprietor (the same taxpayer whose socialSecurityWages are supplied), with no depreciation/§179/bonus, no SE health-insurance (§162(l)) or home-office (§280A), not farm/clergy/statutory-employee, not a §1402 optional method, and not two spouses' combined self-employment (the OASDI cap is per-individual). Absent → decline. (The §199A QBI deduction is the separate opt-in scheduleCQbiEligible.)"},"scheduleCQbiEligible":{"type":"boolean","enum":[true],"description":"§199A QBI opt-in (below-threshold only). When true (with a positive affirmed scheduleCIncome), computes the 20% QBI deduction = min(20% × (Schedule C net − §164(f) half-SE), 20% × (taxable income − net capital gain)) [Form 8995], reducing taxable income. Attests: (a) a QUALIFIED §162 trade/business; (b) NO self-employed retirement (SEP/SIMPLE/solo-401k), SE health-insurance, or other QBI-reducing deduction beyond the half-SE the engine already subtracts (overstating QBI under-taxes). The engine computes the taxable-income threshold ($197,300 single/HoH/MFS, $394,600 MFJ, 2025) and DECLINES the at/above-threshold case (Form 8995-A wage/UBIA/SSTB, engine-invisible). Absent → no QBI (over-tax-safe). Federal-only (CA does not conform to §199A)."},"socialSecurityWages":{"type":"number","description":"W-2 box 3 — the SE earner's own Social-Security wages+tips (≥0). REQUIRED (fail-closed) when scheduleCIncome is present AND the return has W-2 wages: W-2 SS wages already used part of the combined $176,100 OASDI ceiling (Schedule SE lines 8–9), so the SE OASDI is capped at the REMAINING room. Absent-with-wages → schedule_c_se_needs_social_security_wages (assuming $0 would over-collect OASDI → inflate the §164(f) deduction → under-tax a phase-out). An explicit 0 affirms no W-2 SS wages. Box 5 (medicareWages) is uncapped and cannot substitute. Federal-only."},"scheduleEIncome":{"type":"number","description":"Schedule E net. A POSITIVE value COMPUTES a simple passive rental (→ Schedule 1 line 5 → Schedule 1 line 10 → Form 1040 line 8 → AGI + §1411 NIIT) but REQUIRES both scheduleERentalIsPassiveFinalNet:true AND scheduleERentalNotSection162Business:true. A LOSS, a missing affirmation, or a §162/QBI rental → schedule_e_needs_review decline. STATE: NY CONFORMS (iteration 43, NARROW — taxes the passive net in NY AGI as ordinary income), requiring nyScheduleENoStateBusinessAdjustmentsAffirmed:true (straight-line real property, no §168(k)/cost-seg/§179). CA rejects it (CA runs a separate §469 passive track — FTB 3801/3885A — deferred)."},"scheduleERentalIsPassiveFinalNet":{"type":"boolean","enum":[true],"description":"§6694 affirmation REQUIRED for a positive scheduleEIncome: attests it is the FINAL Schedule E line-26 PASSIVE net — post depreciation/§465 at-risk/absorbed §469 suspended losses, no property disposition (no §1250 recapture), rental real estate only (no royalties/K-1), no AMT depreciation adjustment. Absent → decline."},"scheduleERentalNotSection162Business":{"type":"boolean","enum":[true],"description":"§6694 affirmation REQUIRED for a positive scheduleEIncome: attests the rental is NOT a §162 trade/business (Notice 2019-07 safe harbor), so no §199A QBI 20% deduction applies. If it IS, a preparer must compute the QBI deduction (omitting it would over-tax). Absent → decline."},"pensionDistributionTaxable":{"type":"number","description":"1040 line 5b — the FULLY-TAXABLE portion of a pension/annuity/IRA distribution (1099-R box 2a). ORDINARY income → AGI + ordinary tax ONLY; NOT in the §1411 NIIT base (pension is not net investment income) and NOT in the Additional-Medicare base (not wages). A POSITIVE value COMPUTES only with pensionDistributionFullyTaxableAffirmed:true. Basis/after-tax, QCD, rollover, Roth conversion, NUA, and the early-distribution 10% additional tax are NOT modeled → pension_needs_review decline (do not affirm). NY EXCLUDES it on the state return (iteration 30 — IT-201 line 26 govt / line 29 private $20k@59½); CA CONFORMS and TAXES it (iteration 32 — a CA pension return computes, no exclusion, with a Tier-2-railroad VERIFY flag)."},"pensionDistributionFullyTaxableAffirmed":{"type":"boolean","enum":[true],"description":"§6694 affirmation REQUIRED for a positive pensionDistributionTaxable: attests the amount is the FULLY-TAXABLE 1099-R box 2a distribution (taxable amount DETERMINED — box 2b NOT checked), with NO basis/after-tax contributions, and that it is NOT a QCD, rollover, Roth conversion, NUA, or subject to the early-distribution 10% additional tax. Absent → the distribution declines (pension_needs_review)."},"qualifyingChildrenForCtc":{"type":"integer","description":"Number of qualifying children under 17 (SSN, dependent) for the Child Tax Credit — Schedule 8812 Part I (nonrefundable; the refundable ACTC is a later slice). $2,200 each (2025, OBBBA), phased out 5% of AGI over $400k MFJ / $200k others (excess rounded up to the next $1,000), limited to tax liability. REQUIRES childTaxCreditChildrenQualifyAffirmed."},"childTaxCreditChildrenQualifyAffirmed":{"type":"boolean","enum":[true],"description":"§6694 affirmation REQUIRED for a positive qualifyingChildrenForCtc: attests EVERY child is under 17 at year-end, has an employment-valid SSN by the due date, is your dependent, a US citizen/national/resident, lived with you > half the year, and did not provide > half their own support. Absent → declines (child_tax_credit_needs_review)."},"otherDependentsForOdc":{"type":"integer","description":"Number of other dependents for the $500 Credit for Other Dependents (ODC) — Schedule 8812 Part I. Dependents who are NOT CTC-qualifying children. Same MAGI phase-out. REQUIRES otherDependentsQualifyForOdcAffirmed."},"otherDependentsQualifyForOdcAffirmed":{"type":"boolean","enum":[true],"description":"§6694 affirmation REQUIRED for a positive otherDependentsForOdc: attests each is your dependent, a US citizen/national/resident with a TIN by the due date, and is NOT also a CTC qualifying child. Absent → declines (child_tax_credit_needs_review)."},"socialSecurityBenefits":{"type":"number","description":"SSA-1099 box 5 — GROSS Social Security benefits (≥0; a negative repayment is schema-rejected). The TAXABLE portion (1040 line 6b) is COMPUTED via the §86 worksheet (0/50/85% tiers by provisional income = other AGI + tax-exempt interest + ½ benefits; base $25k single/$32k MFJ/$0 MFS-lived-with-spouse, adjusted $34k/$44k). ORDINARY income → AGI + ordinary tax ONLY (NOT NIIT, NOT Additional Medicare). REQUIRES socialSecurityStandardCaseAffirmed:true AND taxExemptInterest supplied AND (for MFS) socialSecurityMfsLivedWithSpouse; §86(e) lump-sum / foreign / railroad RRB-1099 → social_security_needs_review decline. CA/NY fully EXCLUDE the taxable SS on the state return (iteration 29 — Schedule CA (540) line 6 col B / IT-201 line 27)."},"taxExemptInterest":{"type":"number","description":"1040 line 2a — tax-exempt (municipal-bond) interest. NOT taxable / NOT in AGI, but ADDED to the §86 Social Security provisional-income calc. REQUIRED whenever socialSecurityBenefits is present (undefined ≠ zero → decline, because omitting it understates provisional income and UNDER-taxes the benefits; an explicit 0 affirms no tax-exempt interest). A POSITIVE value ALSO requires taxExemptInterestNoPrivateActivityBonds:true (line 2a may include private-activity-bond interest — a positive AMT preference the engine does not model, so a positive amount without the no-PAB affirmation declines)."},"taxExemptInterestNoPrivateActivityBonds":{"type":"boolean","enum":[true],"description":"§6694 affirmation REQUIRED for a positive taxExemptInterest: attests NONE of it is specified private-activity-bond interest (1099-INT box 9 / Form 6251 line 2g), a positive AMT preference. The engine does not route tax-exempt interest into the AMT computation, so an unaffirmed positive amount could under-state AMT → declines (social_security_needs_review). An explicit taxExemptInterest:0 needs no affirmation."},"socialSecurityStandardCaseAffirmed":{"type":"boolean","enum":[true],"description":"§6694 affirmation REQUIRED for a positive socialSecurityBenefits: attests box 5 is a STANDARD current-year SSA-1099 net (Medicare already netted), NOT a §86(e) lump-sum election, NOT foreign/totalization benefits, NOT railroad RRB-1099 Tier-1. Absent → the benefits decline (social_security_needs_review)."},"socialSecurityMfsLivedWithSpouse":{"type":"boolean","description":"REQUIRED for a married_filing_separately filer with Social Security: true if the filer lived with their spouse any time during the year (→ §86 base $0, up to 85% taxable from the first dollar), false if lived apart all year (→ treated like single). Absent for MFS+SS → decline (the engine cannot infer it and would under-tax a lived-with-spouse filer)."},"netShortTermCapGain":{"type":"number","description":"Pre-netted scalar net short-term capital gain/loss (Schedule D). Lot-level/8949 detail, wash sales, §1256, covered-basis decline."},"netLongTermCapGain":{"type":"number","description":"Pre-netted scalar net long-term capital gain/loss (Schedule D). The §1250-unrecaptured (25%) and 28%-collectibles special-rate PORTIONS of this gain are asserted separately via sec1250UnrecapturedGain / collectibles28Gain (2025; see those fields)."},"sec1250UnrecapturedGain":{"type":"number","minimum":0,"description":"Caller-asserted UNRECAPTURED §1250 gain (Schedule D line 19) — the depreciation-recapture PORTION of the net long-term capital gain taxed at a MAX 25% rate (§1(h)(1)(E)). A SUBSET of netLongTermCapGain: sec1250UnrecapturedGain + collectibles28Gain MUST be ≤ netLongTermCapGain, else the return declines as contradictory (fail-closed — never capped-and-under-taxed). Present → the FULL Schedule D Tax Worksheet computes (the 25% slice stacked above the 0/15/20 bands, floored at ordinary tax on all taxable income). §6694: omitting a real §1250 portion UNDER-taxes it at 0/15/20, so the preparer must assert it. MODELED for 2025 only (other years → special_rate_gain_unmodeled decline); scalar netLongTermCapGain path (not capGainAggregates)."},"collectibles28Gain":{"type":"number","minimum":0,"description":"Caller-asserted 28%-RATE gain (Schedule D line 18) — collectibles (§408(m)) plus the taxable portion of §1202 QSBS gain, taxed at a MAX 28% rate (§1(h)(1)(F)/(4)). A SUBSET of netLongTermCapGain: sec1250UnrecapturedGain + collectibles28Gain MUST be ≤ netLongTermCapGain, else the return declines as contradictory. Present → the FULL Schedule D Tax Worksheet computes (the 28% slice stacked above the 0/15/20 bands, floored at ordinary tax on all taxable income). §6694: omitting real 28%-rate gain UNDER-taxes it at 0/15/20. MODELED for 2025 only; scalar netLongTermCapGain path."},"priorYearCapLossCarryoverST":{"type":"number","minimum":0,"description":"Prior-year SHORT-term capital-loss carryover — POSITIVE magnitude (caller-asserted). Applied with the §1211(b) −$3,000 (−$1,500 MFS) annual limit; ending carryover returned as endingCapLossCarryoverST."},"priorYearCapLossCarryoverLT":{"type":"number","minimum":0,"description":"Prior-year LONG-term capital-loss carryover — POSITIVE magnitude (caller-asserted). Nets against long-term gain; ending carryover returned as endingCapLossCarryoverLT."},"digitalAssetAllAcquiredByPurchase":{"type":"boolean","enum":[true],"description":"§6694 affirmation (#1 of 3) to COMPUTE a covered digital-asset (crypto) disposition. Attests every unit in every capGainAggregates digitalAsset box was acquired by PURCHASE — none via staking, mining, airdrop/hard fork, or as payment (those carry separate ordinary income at FMV, Rev. Rul. 2023-14, invisible to a disposition compute). Only a TY2026+ COVERED (box A/D) crypto box with ALL THREE affirmations computes; pre-2026, noncovered B/E, wash-flagged, or missing-affirmation crypto → digital_asset_needs_review decline. Federal-only (state schemas reject it)."},"digitalAssetNoneAreCollectible":{"type":"boolean","enum":[true],"description":"§6694 affirmation (#2 of 3) to COMPUTE a covered digital-asset disposition. Attests NO disposed unit is a §408(m) COLLECTIBLE — none is an NFT treated as a collectible under the Notice 2023-27 look-through, which would tax the long-term gain at 28% instead of the §1(h) 0/15/20 bands. Absent → the crypto box declines (the engine nets at 0/15/20 and cannot see collectible character). Federal-only."},"digitalAssetIsCapitalNotOrdinary":{"type":"boolean","enum":[true],"description":"§6694 affirmation (#3 of 3) to COMPUTE a covered digital-asset disposition. Attests the gain is CAPITAL, not ordinary: every unit is a §1221 capital asset (NOT dealer/inventory/customer property held for sale — crypto held that way is ordinary per Notice 2014-21), there is no Form 1099-DA Box-6 ordinary gain/loss, and no non-USD/§988 foreign-currency ordinary treatment. Absent → decline (the engine nets at preferential capital rates and cannot see dealer/inventory/§988 ordinary character). Crypto affirmations require a tagged capGainAggregates digitalAsset box (they decline on scalar netLongTermCapGain). Federal-only."},"capGainAggregates":{"type":"array","minItems":1,"description":"Schedule D / Form 8949 per-BOX 1099-B aggregates (NOT individual lots). The engine nets covered-clean boxes into ST/LT itself (A/B=short, D/E=long; A/D=covered, B/E=noncovered), across multiple brokers. COMPUTES only covered (A/D) boxes with a present positive basis, no wash flag, no adjustment code; ANY other box → whole-return decline (capital_gain_lots_need_review), no tax-number leakage. Mutually exclusive with netShortTermCapGain/netLongTermCapGain. Every multi-broker computed return carries a cross-account wash-sale VERIFY flag.","items":{"type":"object","additionalProperties":false,"required":["broker","boxType","proceeds"],"properties":{"broker":{"type":"string","minLength":1,"description":"Broker/payer name (used to detect multi-broker returns)."},"boxType":{"type":"string","enum":["A","B","D","E"],"description":"Form 8949 box: A/B = short-term, D/E = long-term; A/D = covered (basis reported to IRS), B/E = noncovered (declines)."},"proceeds":{"type":"number","minimum":0,"description":"Total proceeds for this box."},"basis":{"type":"number","minimum":0,"description":"Total cost basis for this box. Required for a covered (A/D) box; blank/zero → decline (unknown-basis)."},"washSaleDisallowed":{"type":"number","minimum":0,"description":"If present and > 0, wash-sale computation is out of scope → the box declines."},"hasAdjustmentCode":{"type":"boolean","description":"If true (any Form 8949 adjustment code — wash/§1256/equity-comp/collectibles/§1250), the box declines."},"digitalAsset":{"type":"boolean","description":"Mark a digital-asset (crypto) disposition (Form 1099-DA / Form 8949). A TY2026+ COVERED (box A/D) box COMPUTES proceeds−basis as a capital gain ONLY with the three return-level affirmations (digitalAssetAllAcquiredByPurchase + digitalAssetNoneAreCollectible + digitalAssetIsCapitalNotOrdinary); pre-2026 (proceeds-only 1099-DA), noncovered B/E, wash-flagged, or a missing affirmation → digital_asset_needs_review decline (reason names basis, staking/mining/airdrop-as-ordinary-income, §408(m)-collectible, §1221/§475(f)/§988 ordinary character, and §1091-inapplicability). No tax-number leakage."},"sec1256":{"type":"boolean","description":"Mark a §1256 contract (regulated futures / broad-based index options; 1099-B box 11 → Form 6781) → a §1256-specific whole-return decline (section_1256_needs_review). The engine does not compute the 60/40 split (inseparable from §475(f) MTM, straddles, loss-carryback). No tax-number leakage."},"equityCompType":{"type":"string","enum":["RSU","ESPP","ISO","NSO"],"description":"Tag an equity-compensation sale → grant-type-specific whole-return decline (equity_comp_basis_adjustment_needs_review) naming the exact adjustment a preparer must apply. The engine does not attest a broker Stock-Plan-Supplement adjusted basis (§6694 policy boundary). No tax-number leakage."}}}},"mortgageInterest":{"type":"number","description":"Schedule A — home mortgage interest (1098 box 1). Requires mortgageAvgBalance."},"mortgageAvgBalance":{"type":"number","description":"Average home-acquisition-debt balance — basis for the §163(h)(3) $750k limit; the engine prorates interest above it. Required with mortgageInterest."},"stateLocalIncomeTax":{"type":"number","description":"Schedule A — state/local income tax (W-2 box 17). Part of the OBBBA-2025 SALT cap."},"realEstateTax":{"type":"number","description":"Schedule A — real-estate (property) tax. Part of the SALT cap."},"foreignTaxPaid":{"type":"number","description":"Creditable foreign tax (1099-DIV box 7). §904(j) de-minimis only (≤$300/$600 MFJ); requires foreignIncomeAllPassive1099. Over-ceiling declines."},"foreignIncomeAllPassive1099":{"type":"boolean","enum":[true],"description":"Required with foreignTaxPaid: affirm ALL foreign income is passive + 1099-reported (the §904(j) election validity condition)."}}},"StateProfile":{"type":"object","required":["state","year"],"properties":{"state":{"type":"string","enum":["ca","ny"]},"year":{"type":"integer","example":2025},"wages":{"type":"number"},"nyWageAdditions":{"type":"number","description":"NY only — 414(h)/IRC-125 add-backs (NY fails closed without it)"},"taxableInterest":{"type":"number","description":"Requires stateIncomeConformsToFederal:true (else non-wage income declines)."},"ordinaryDividends":{"type":"number","description":"Requires stateIncomeConformsToFederal:true."},"netLongTermCapGain":{"type":"number","description":"Taxed as ordinary by CA/NY; requires stateIncomeConformsToFederal:true."},"netShortTermCapGain":{"type":"number","description":"Taxed as ordinary by CA/NY; requires stateIncomeConformsToFederal:true."},"qualifiedDividends":{"type":"number","description":"≤ ordinaryDividends; CA/NY tax it as ordinary (no preferential rate); requires stateIncomeConformsToFederal:true."},"stateIncomeConformsToFederal":{"type":"boolean","enum":[true],"description":"§6694 whitelist affirmation: ALL non-wage income is clean state-conforming (no tax-exempt/out-of-state-muni interest, no exempt-interest dividends OTHER THAN the out-of-state portion supplied as caOutOfStateMuniInterestAddition, no US-Treasury-obligation interest needing a CA subtraction OTHER THAN the explicitly-supplied caUsObligationInterestSubtraction (direct) or caUsObligationRicDividendSubtraction (RIC dividend, §17145), basis == federal). Required to compute non-wage income; absent → non-wage declines."},"caScheduleCSelfEmployedForCaPurposesAffirmed":{"type":"boolean","enum":[true],"description":"CA only — §6694 affirmation REQUIRED with a Schedule C net on the CA return (iteration 39). Attests the taxpayer is SELF-EMPLOYED FOR CALIFORNIA PURPOSES (NOT reclassified as an employee under AB5 / the Dynamex ABC test). CA disallows the §164(f) one-half-SE-tax deduction for a federal contractor who is a CA employee (Schedule CA 540 line 15) → taking federal AGI would under-tax by the half-SE amount; the engine cannot see CA worker classification, so absent/false → CA declines. Also requires caScheduleCNoStateBusinessAdjustmentsAffirmed."},"caScheduleCNoStateBusinessAdjustmentsAffirmed":{"type":"boolean","enum":[true],"description":"CA only — §6694 affirmation REQUIRED with a Schedule C net on the CA return (Codex R251-001). Attests the federal Schedule C net has ZERO California business-income adjustments (Schedule CA 540 line 3 / FTB Pub 1001): no CA/federal depreciation or §179 difference (CA §179 cap is $25,000; CA does not conform to bonus depreciation), no PPP/EIDL/grant/loan-forgiveness exclusion difference, no fringe-benefit / accelerated-write-off / other Pub-1001 business-income or basis adjustment. AB5 classification alone is not sufficient — a CA line-3 addition the engine cannot see would under-tax; absent/false → CA declines (a preparer must make the Schedule CA line-3 adjustment)."},"nyScheduleCNoStateBusinessAdjustmentsAffirmed":{"type":"boolean","enum":[true],"description":"NY only — §6694 affirmation REQUIRED with a Schedule C net on the NY return (iteration 42). Attests the federal Schedule C net has ZERO New York business-income adjustments (Form IT-225): no §168(k) bonus-depreciation difference (NY decouples — addition A-209 / Form IT-398), no 2025 research-&-experimental decoupling (Notice N-26-1, tax years beginning on/after 1/1/2025), no §179-SUV or other §179 difference, no other IT-225 A-series business-income modification. NY starts from federal AGI, so a NY addition the engine cannot see would under-tax; absent/false → NY declines (ny_schedule_c_adjustment_needs_review). NY needs NO worker-classification affirmation (no AB5/§164(f) disallowance). Separate NY MCTMT + NYC-UBT are surfaced as a VERIFY flag, not computed."},"nyScheduleENoStateBusinessAdjustmentsAffirmed":{"type":"boolean","enum":[true],"description":"NY only — §6694 affirmation REQUIRED with a Schedule E rental net on the NY return (iteration 43). Attests the federal rental net has ZERO New York depreciation adjustments (Form IT-225 / IT-398): STRAIGHT-LINE real-property depreciation (27.5-yr residential / 39-yr commercial), no §168(k) bonus, no cost-segregation 5/7/15-yr or QIP bonus component, no §179. NY conforms to the federal §469 passive rules (no separate NY PAL adjustment). A cost-seg/bonus component would be a NY addition the engine cannot see → under-tax; absent/false → NY declines (ny_schedule_e_adjustment_needs_review). Also requires the two federal affirmations scheduleERentalIsPassiveFinalNet + scheduleERentalNotSection162Business."},"caItemizedDeductions":{"type":"number","description":"CA only — the FINAL California Schedule CA (540) Part II line 30 itemized total, AFTER the CA state-and-local-income-tax disallowance (line 5a) AND the CA high-income itemized-deduction reduction worksheet (6% of AGI over the threshold). NOT the federal Schedule A total (which is higher → would under-tax). Form 540 line 18 = greater-of(CA standard deduction, this). REQUIRES itemizedDeductionsAreFinalStateAmount:true (else declines); MFS declines (spouse's §63(c)(6)(A) election). The engine consumes it, does not derive or limit it."},"caUsObligationInterestSubtraction":{"type":"number","description":"CA only — Schedule CA (540) Part I line 2 col B: the US-government-obligation interest SUBTRACTION (R&TC §17143; US-Treasury interest is federally taxable but CA-exempt). Caller-asserted amount of the DIRECT US-obligation interest included in federal taxable interest (1040 line 2b), subtracted from CA AGI ONLY (not federal AGI). REQUIRES caUsObligationInterestAffirmed:true and is CAPPED at the supplied taxableInterest (exceeds → declines). A RIC/§17145 fund distribution is out of scope (declined). A subtraction over-claimed under-taxes → fails closed without the affirmation."},"caUsObligationInterestAffirmed":{"type":"boolean","enum":[true],"description":"CA only — §6694 affirmation REQUIRED when caUsObligationInterestSubtraction is supplied: attests the amount is DIRECT US-Treasury/US-government-obligation interest included in your federal taxable interest (line 2b), NOT a RIC/mutual-fund (§17145) distribution, and ≤ that included interest. Absent → the subtraction declines."},"caUsObligationRicDividendSubtraction":{"type":"number","description":"CA only — Schedule CA (540) Part I line 2 col B: the RIC/mutual-fund US-government-obligation DIVIDEND subtraction (R&TC §17145). A fund holding ≥50% of assets in US-government (and CA-exempt) obligations AT EACH QUARTER-END may pass the US-obligation-interest PORTION of its ORDINARY dividend (1099-DIV box 1a / line 3b) through as CA-exempt — this is the RIC case caUsObligationInterestSubtraction (direct interest, line 2b) declines. Subtracted from CA AGI ONLY (not federal AGI). REQUIRES the two-part caUsObligationRicDividendAffirmed:true and is CAPPED at non-qualified ordinary dividends (ordinaryDividends − qualifiedDividends; US-obligation interest is never a qualified dividend). The 50%-asset test is a CLIFF: below 50%, NONE is exempt (do not supply). A subtraction over-claimed under-taxes → fails closed without the affirmation."},"caUsObligationRicDividendAffirmed":{"type":"boolean","enum":[true],"description":"CA only — §6694 TWO-PART affirmation REQUIRED when caUsObligationRicDividendSubtraction is supplied, attesting PER THE FUND'S OWN WRITTEN SHAREHOLDER TAX STATEMENT: (1) the amount is the US-government-obligation interest portion of the fund's ordinary dividend (1099-DIV box 1a) in your federal AGI, AND (2) the fund's statement affirms it MET California's ≥50%-US-obligation-assets-at-each-quarter test (§17145). Absent → the subtraction declines."},"caHsaEmployerContributionAddition":{"type":"number","description":"CA only — Schedule CA (540) Part I Section A line 1h col C: HSA employer/cafeteria-plan contribution (W-2 box 12 code W), excluded from federal box-1 wages but CA-taxable (R&TC §17131.4, IRC §106(d); CA does not recognize HSAs). ADDED to CA AGI ONLY (never federal AGI). REQUIRES caHsaAddbacksAffirmed:true. Over-tax-safe (an addition). Do NOT also report it in wages."},"caHsaInterestAddition":{"type":"number","description":"CA only — Schedule CA (540) Part I Section A line 2 col C: interest earned INSIDE an HSA (federally tax-deferred, CA-taxable in the year earned; §17215.4, IRC §223). ADDED to CA AGI ONLY. REQUIRES caHsaAddbacksAffirmed:true. Do NOT also report it in taxableInterest (double-count)."},"caHsaDividendAddition":{"type":"number","description":"CA only — Schedule CA (540) Part I Section A line 3 col C: taxable dividends earned INSIDE an HSA (CA-taxable in the year earned; §17215.4, IRC §223). ADDED to CA AGI ONLY. REQUIRES caHsaAddbacksAffirmed:true. Do NOT also report it in ordinaryDividends (double-count). NOTE: the SELF-contribution HSA deduction is NOT added back (the engine takes no federal HSA deduction to reverse); HSA distributions + Archer-MSA rollover (R&TC §17215, IRC §220, +12.5%) are out of scope."},"caHsaAddbacksAffirmed":{"type":"boolean","enum":[true],"description":"CA only — §6694 affirmation REQUIRED when any caHsa*Addition is supplied: attests each amount is the CA-taxable HSA add-back for its category and is NOT also reported in wages / taxableInterest / ordinaryDividends. Absent → the HSA add-backs decline (fail-closed)."},"caOutOfStateMuniInterestAddition":{"type":"number","description":"CA only — Schedule CA (540) Part I line 2 col C: the OUT-OF-STATE municipal / exempt-interest-dividend interest ADDITION. Box-12 exempt-interest dividends (and any other tax-exempt interest) from NON-California municipal obligations are federally tax-exempt (never in federal AGI) but CA-taxable → ADDED to CA AGI ONLY (not federal AGI). CA munis AND US-territory munis (Puerto Rico/Guam/USVI, exempt in all states) stay CA-exempt and are EXCLUDED — BUT California's 50%-asset test makes the ENTIRE fund exempt-interest dividend CA-taxable (including the CA portion) when the fund holds <50% of assets in CA/US-territory/US-government obligations. REQUIRES caOutOfStateMuniInterestAffirmed:true (else declines). An addition is over-tax-safe; there is NO engine-visible cap (exempt-interest dividends never enter federal AGI), so the affirmation is the sole guard. NOT conformity-gated (a wages-only filer may supply it)."},"caOutOfStateMuniInterestAffirmed":{"type":"boolean","enum":[true],"description":"CA only — §6694 affirmation REQUIRED when caOutOfStateMuniInterestAddition is supplied: attests the amount is the CA-taxable portion of your box-12 exempt-interest dividends / tax-exempt interest — normally the portion from NON-California municipal obligations (CA munis AND US-territory munis — Puerto Rico/Guam/USVI — EXCLUDED), or the ENTIRE dividend when California's 50%-asset test fails. Absent → the addition declines."},"nyItemizedDeductions":{"type":"number","description":"NY only — the FINAL New York Form IT-196 line 49 itemized total, AFTER the NY state/local income-tax ADDBACK and the NY high-income itemized LIMITATION worksheet (IT-196-I line 47: itemized limited to 50% of line-19 gifts-to-charity for NYAGI $1,000,000–$10,000,000, and 25% of line 19 for NYAGI over $10,000,000; line 48 then adds the college-tuition itemized deduction). NOT the federal Schedule A total (which is higher → would under-tax). IT-201 line 34 = greater-of(NY standard deduction, this). REQUIRES itemizedDeductionsAreFinalStateAmount:true (else declines); MFS declines (spouse's §63(c)(6)(A) election). The engine consumes it, does not derive, verify, or apply the IT-196 limitation."},"itemizedDeductionsAreFinalStateAmount":{"type":"boolean","enum":[true],"description":"§6694 affirmation REQUIRED when caItemizedDeductions or nyItemizedDeductions is supplied: attests the amount is the FINAL state itemized total (CA Schedule CA line 30 / NY IT-196 line 49 — post state adjustments AND the state high-income limitation), NOT the federal Schedule A total. Absent → the itemized amount is DECLINED (fail-closed), preventing a silent federal-Schedule-A under-tax."},"socialSecurityBenefits":{"type":"number","description":"GROSS Social Security benefits (SSA-1099 box 5). Both CA and NY FULLY EXCLUDE taxable Social Security: the engine recomputes the federal §86 taxable portion (line 6b) in-process and SUBTRACTS it on Schedule CA (540) line 6 col B (CA) / IT-201 line 27 (NY). REQUIRES socialSecurityStandardCaseAffirmed:true (and socialSecurityMfsLivedWithSpouse for MFS) — the SAME §86 gates as the federal endpoint; an unaffirmed SS return declines federally → declines the state."},"socialSecurityStandardCaseAffirmed":{"type":"boolean","enum":[true],"description":"§6694 affirmation REQUIRED when socialSecurityBenefits is supplied: attests the standard §86 worksheet applies (no lump-sum election, no Form 8815/foreign-earned-income/§931-933 add-backs, no Roth-conversion or other provisional-income complications the engine does not model). Absent → declines (fail-closed)."},"socialSecurityMfsLivedWithSpouse":{"type":"boolean","description":"REQUIRED (either boolean) when socialSecurityBenefits is supplied AND filingStatus is married_filing_separately: whether the taxpayer lived with their spouse at any time during the year (§86(c)(1)(C) sets the MFS base amount to $0 if true). Absent for MFS+SS → declines."},"taxExemptInterest":{"type":"number","description":"Tax-exempt interest (1040 line 2a) — a §86 provisional-income operand. Accepted so the state's federal §86 recompute is correct, BUT any positive amount DECLINES the state return (state_tax_exempt_interest_unsupported): the CA out-of-state-muni add-back (Schedule CA line 2 col C) / NY non-NY-muni add-back (IT-225 A-101) is not sized in this slice. Supply Social Security WITHOUT tax-exempt interest to compute."},"taxExemptInterestNoPrivateActivityBonds":{"type":"boolean","enum":[true],"description":"§6694 affirmation paired with taxExemptInterest for the federal §86/AMT path (attests no specified private-activity-bond interest, Form 6251 line 2g). On the state path a positive taxExemptInterest declines regardless, so this only matters if the field is ever un-gated in a later slice."},"pensionDistributionTaxable":{"type":"number","description":"State (CA + NY) — the fully-taxable federal line-5b pension/IRA distribution (with pensionDistributionFullyTaxableAffirmed:true). NY EXCLUDES it: supply nyPensionIsGovernmentPension (IT-201 line 26, full) OR nyPrivatePensionQualifiesFor20kExclusion (IT-201 line 29, min($20k,5b)); neither → the pension stays NY-taxable. CA CONFORMS and TAXES it (no exclusion; a Tier-2-railroad VERIFY flag names the one CA divergence, 45 U.S.C. §231m)."},"pensionDistributionFullyTaxableAffirmed":{"type":"boolean","enum":[true],"description":"§6694 affirmation REQUIRED for a positive pensionDistributionTaxable (same contract as the federal endpoint): the fully-taxable 1099-R box 2a distribution, no basis/QCD/rollover/Roth/NUA/early-penalty."},"nyPensionIsGovernmentPension":{"type":"boolean","enum":[true],"description":"NY only — §6694 affirmation for the IT-201 line 26 GOVERNMENT-pension FULL exclusion (§612(c)(3)): attests the ENTIRE federal line-5b amount is a NYS/local-NY/federal government-EMPLOYER pension (incl. U.S. military), NO private/IRA/annuity component. Per IT-201-I, IRC §457 GOVERNMENT deferred-comp is EXPLICITLY NOT a line-26 item (it goes to the line-29 private $20k path) — do NOT affirm this for a §457 distribution. NY excludes 100% (uncapped). Line 5b is a single scalar → a mixed govt+private (or govt+§457) 5b must NOT affirm (→ pension taxed, or a preparer splits). Mutually exclusive with nyPrivatePensionQualifiesFor20kExclusion (both → decline)."},"nyPrivatePensionQualifiesFor20kExclusion":{"type":"boolean","enum":[true],"description":"NY only — §6694 affirmation for the IT-201 line 29 PRIVATE pension/annuity exclusion (§612(c)(3-a), up to $20,000): attests (a) the recipient was age 59½ BEFORE January 1, 2025 (a taxpayer who became 59½ during 2025 must NOT affirm), AND (b) the ENTIRE federal line-5b amount is qualifying periodic pension/annuity income (no Form 4972 lump-sum, no after-retirement 401(k), no non-qualifying portion). NY excludes min($20,000, line 5b). Mutually exclusive with nyPensionIsGovernmentPension (both → decline)."}}},"NextAction":{"type":"string","description":"Stable machine-actionable next step (uniform across every response; same set in docs + live).","enum":["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"]},"ComputeResult":{"type":"object","description":"An HTTP 200 is billable whether the engine COMPUTED a result or honestly DECLINED. Every 200 carries the uniform contract fields: `billed` (ledger truth — did this call write a billed usage_event), `retry_safe` (safe ONLY as a same-Idempotency-Key replay — NEVER mint a new key to avoid duplicate billing), `next_action`, and — on a successful compute — `provenance` (deterministic derivation basis) plus `legal_notice` (a stable not-tax-advice notice). A decline carries `code` + `reason` and `next_action: review_inputs`.","properties":{"computed":{"type":"boolean"},"billed":{"type":"boolean"},"retry_safe":{"type":"boolean"},"next_action":{"$ref":"#/components/schemas/NextAction"},"provenance":{"type":"object","description":"Deterministic derivation basis; present on successful computed/workflow responses only."},"year":{"type":"integer","description":"Tax year computed (computed:true)."},"filingStatus":{"type":"string","description":"Filing status computed (computed:true)."},"taxableIncome":{"type":"integer","description":"Line 15 — taxable income, whole dollars (computed:true)."},"incomeTax":{"type":"integer","description":"Line 16 — income tax before other taxes/credits (computed:true)."},"totalTax":{"type":"integer","description":"Line 22/24 — total tax including NIIT/Additional-Medicare (computed:true)."},"owedOrRefund":{"type":"integer","description":"Owed (positive) or refund (negative); totalTax − withholding − ACTC. Present when federalWithholding is supplied OR a refundable Additional Child Tax Credit is present (which can make it negative with no withholding)."},"additionalChildTaxCredit":{"type":"integer","description":"Refundable Additional Child Tax Credit (Schedule 8812 Part II → 1040 line 28); present only when > 0. Capped at min(unused CTC, qualifying-children × $1,700, 15% × (W-2 wages − $2,500))."},"endingCapLossCarryoverST":{"type":"integer","description":"Schedule D SHORT-term capital-loss carryover to NEXT year (positive magnitude). Present only when non-zero. Feed back as next year's priorYearCapLossCarryoverST."},"endingCapLossCarryoverLT":{"type":"integer","description":"Schedule D LONG-term capital-loss carryover to NEXT year (positive magnitude). Present only when non-zero. Feed back as next year's priorYearCapLossCarryoverLT."},"lines":{"type":"array","description":"Per-line breakdown (computed:true); each carries its own primary-source derivation.","items":{"type":"object","properties":{"lineId":{"type":"string","example":"1040:16"},"label":{"type":"string"},"amount":{"type":"number"},"derivation":{"type":"array","items":{"type":"object"},"description":"Primary-source derivation basis for the line."}}}},"flags":{"type":"array","items":{"type":"string"},"description":"Advisory engine flags (non-authoritative notes)."},"legal_notice":{"$ref":"#/components/schemas/LegalNotice"},"code":{"$ref":"#/components/schemas/DeclineCode","description":"Decline code (computed:false only)."},"reason":{"type":"string","description":"Decline/explanatory reason."}}},"LegalNotice":{"type":"object","description":"Machine-readable not-tax-advice notice. Present on successful compute (computed:true) and reconcile 200s (NOT on 200 declines). A stable constant — `version` changes only with the wording; `ref` points at the published /terms compute-notice.","properties":{"ref":{"type":"string","example":"https://tax-mcp.com/terms#compute-notice"},"version":{"type":"string","example":"v1"},"text":{"type":"string","description":"The canonical short notice; computation support only, not tax/legal/accounting advice, customer is preparer."}}},"DeclineCode":{"type":"string","description":"Federal decline code (present on a computed:false 200). Stable enum — same set in capabilities + docs + live.","enum":["year_not_modeled","special_rate_gain_unmodeled","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","engine_declined"]},"Error":{"type":"object","description":"Every non-200 body carries the uniform contract fields: `billed` (always false — a rejected/failed call writes no billed event), `retry_safe`, `next_action`, and `reason`. `error` remains the machine discriminator.","properties":{"error":{"type":"string"},"billed":{"type":"boolean","enum":[false]},"retry_safe":{"type":"boolean"},"next_action":{"$ref":"#/components/schemas/NextAction"},"reason":{"type":"string"}}}},"responses":{"BadRequest":{"description":"Invalid body / JSON / failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unauthorized":{"description":"Missing / unknown / revoked key (no enumeration)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"AccountSuspended":{"description":"Account suspended — contact billing (distinct from 401: the key is valid)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"IdempotencyConflict":{"description":"Idempotency-Key reused with a different body (`idempotency_key_reused`), or a concurrent in-flight duplicate (`idempotency_key_in_progress`). Retry; NOT billed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"InternalError":{"description":"Sanitized server error computing the return","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"QuotaOrRate":{"description":"Monthly quota exhausted (account-wide; `quota_exceeded`, next_action `upgrade_plan_or_wait_next_period`, retry_safe false) or per-minute rate exceeded (`rate_limit_exceeded`, next_action `retry_after_backoff`, retry_safe true). Not billed.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"limit":{"type":"integer"},"used":{"type":"integer"},"billed":{"type":"boolean","enum":[false]},"retry_safe":{"type":"boolean"},"next_action":{"$ref":"#/components/schemas/NextAction"},"reason":{"type":"string"}}}}}},"MeteringFailure":{"description":"Metering outage — fail-closed (the call is NOT silently served free)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}