Error and warning catalog

MOCK. These are not official IRS business-rule results. Every code is basis: "illustrative" EXCEPT the four taken from IRS Pub 4164 (R0000-183-01, R0000-185, R0000-904-03, X0000-010; defined in src/rules.ts), and even those are paraphrased and applied loosely. Real rule behavior lives in IRS business-rule files not available here. Do not tell a human "the IRS rejected" anything; say "the mock rejected".

Where codes appear: validate_return / build_return_xml (errors, warnings) and, after submission, get_acknowledgement (errors make status Rejected; warnings do not). Reach column: MCP = reachable through the server tools; test-only = only via code options not enabled by dist/index.js.

Cross-cutting

Code	Basis	Reach	Meaning / fix
SCHEMA	illustrative	MCP	Input failed shape validation (type, missing, unknown key, EIN NN-NNNNNNN, SSN NNN-00-NNNN, enum, date). Fix the field at path. Blocks XML and submission.
XSD	"IRS XSD"	MCP only if a human installed schemas	Real schema error from locally installed IRS XSDs.
UNSUPPORTED_FORM	illustrative	not reachable (enum blocks it)	Unknown form type.
MOCK-W01 / MOCK-W02	illustrative	MCP	Warning: EIN does not start 00- / SSN is not 000-00-0000. Replace with fake values.
R0000-148	illustrative (attributed in text to Pub 5078, not in repo)	MCP	Test transmission with EIN not starting 00. Use 00-NNNNNNN.
HDR-011	illustrative	MCP	EIN starting 00 with production indicator. Production is simulated; switch to test.
HDR-012	illustrative	MCP	atsMode on 94x: EIN must be 00-3000000..00-3999999.
R0000-504-01	illustrative	MCP	Ack-only: EIN 99-9999999 always triggers an "EIN/name mismatch" rejection. Test hook.
R0000-902-01	illustrative	MCP	Ack-only: an accepted return with same form/identifier/period exists in this process. Do not resubmit; use 941-X for corrections or a new period.
R0000-904-03	Pub 4164	MCP	Production indicator with a Software ID not on the process's "passed testing" list (the list is always empty). Use test.
X0000-005-01	illustrative	MCP	forceReject test hook.
X0000-010	Pub 4164	test-only	Manifest SubmissionID with no matching zip entry.
TRN-001/002/003	illustrative (002 cites the Pub 4164 limit of 100)	test-only	Empty, over-100, or duplicate submissions in a container; MCP always sends exactly one.
R941X-001	illustrative	test-only	941-X with no accepted 941, only if requirePrior941For941X enabled (default off).
R941X-W01	illustrative	MCP	Warning: no accepted original 941 in this process for the 941-X. Informational.

Header and signature (all forms with header)

Code	Basis	Meaning / fix
HDR-001	Pub 4164 text cited in message, code illustrative	Software ID must start with two-digit tax year.
HDR-002	illustrative	94x quarterly ID YY99NNNN, annual YY88NNNN.
HDR-W10	illustrative	Warning: production indicator is simulated.
HDR-W20	illustrative	Warning: PIN fields without signatureOption are ignored.
R0000-183-01	Pub 4164	94x with signatureOption: an attachment described 8453-EMP Signature Document is required (header.attachments).
HDR-020	illustrative	PINNumber needs pinEnteredBy.
HDR-021 / HDR-031	illustrative	pinEnteredBy: ERO needs practitionerPin / ero block.
HDR-022	illustrative	pinEnteredBy: Taxpayer needs taxpayerPin.
R0000-185	Pub 4164	94x practitioner PIN all zeros (HDR-023 for non-94x families, HDR-024 for all-zero taxpayer PIN; both illustrative). Use a non-zero fake PIN.
HDR-030	illustrative	Signature option set: signer {name,title,dateSigned} required.

Shared by 941, 944, 941-X (prefix = form)

Code	Meaning / fix
<F>-010..019 (+-RND warning)	Stated total differs from recomputed. Over $1.00 = error, up to $1.00 = -RND warning. Drop stated or fix the number.
<F>-040	Credit claimed with no form8974. -041 form8974 with no credit. -042 amounts differ. -043 credit above simplified employer-share limit. -044 above $500,000 cap. (941, 944 only.)
W45	Warning: credit above $250,000 applies only to employer Medicare tax.
<F>-060	Refund choice with no overpayment. -061 directDeposit without bank. -062 bank without directDeposit.
<F>-W40	Warning: overpayment (or, for 941-X claim, refund) with no refund choice.

Form 941 (F941-)

001 wages with zero employees; 003 FIT > wages; 004 line-4 box with SS/Medicare wages; 020 credit > line 10; 030 lessThan2500 but line 12 >= $2,500; 031 monthly needs monthlyLiability; 032 monthly sum != line 12; 033 semiweekly needs Schedule B total or detail; 034 scheduleBTotal != line 12; 035 Schedule B with lessThan2500; 036 more daily amounts than days in a month; 037 Schedule B total != line 12; 038 scheduleBTotal != detail; 039 Schedule B monthly sums != monthlyLiability; 050 Schedule R totals != return lines; 051 duplicate client EIN; 052 client EIN equals filer. Warnings: W01 SS wages far below Medicare wages; W02 SS wages > wages; W10 deposits below liability by $2,500+; W11 balance due; W12 overpayment; W20 liability $100,000+ (next-day rule); W30 Schedule B with monthly; W53 client EIN not 00. Fix by correcting the input values; all illustrative.

Form 941-X (F941X-)

001 no row differs; 002 claim process but tax increases; 003 claim needs claimCertification; 004 tax increases needs dateDiscovered; 005 corrected FIT > corrected wages. Warnings W03 certification ignored for adjustment; W04 unneeded dateDiscovered; W05 wages down while FIT up; W06 adjustment overreport is credited, not refunded; W10 additional tax due.

Form 944 (F944-)

003 FIT > wages; 004 no-wages box conflict; 020 credit > total; 030 lessThan2500 but total >= $2,500; 031 monthly needs 12 values; 032 monthly sum mismatch; 033 semiweekly needs liabilitySchedule945A; 034 too many daily amounts; 035 daily total mismatch; 050 final-return date outside year; 051 irsNotifiedToFile944 false. Warnings W01 total > $1,000 confirm eligibility; W10 balance due; W12 overpayment.

Form 7004 (F7004-)

001 period end not in tax year/next; 002 1042 / 706-GS(T) not calendar year; 003 1041 needs estateVariant; 004 short year needs reason; 005 reason without short year; 006 payment without method; 007 method without payment; 008 ACH without bank; 009 ACH payment without ERO PIN or achDebitAgreement; 010 stated balance mismatch. Warnings W03 estateVariant only for 1041; W04 1120-F special dates not modeled; W08 bank only for ACH; W09 no signature needed without payment; W10 paid > balance; W11 balance unpaid.

Not reachable

F940-001/020/021/W10/W11/W12 exist in code for Form 940, which is intentionally not exposed.