Transcript Errors & Status Reference

Status values

Every transcript request in TRH passes through one of the following statuses. The dispatcher updates the row in real time as the request progresses.

Status	Meaning	What to do
Queued	Request is staged in the dispatch queue but has not yet been sent to the IRS. Waiting for an available concurrency slot.	Nothing. Click Start Dispatch if the queue isn't running.
Processing	Request has been sent to the IRS and TRH is waiting for the response.	Wait. Most pulls return within 5 to 60 seconds.
Authenticating	TRH is negotiating the A2A signed-token handshake with the IRS before sending the request.	Wait. If it stays here for more than 60 seconds, test your A2A credentials.
Retrying	The initial attempt failed on a transient error (timeout, 5xx, rate-limit backoff). TRH is waiting out the backoff interval before trying again.	Wait. TRH retries automatically with exponential backoff. No action needed unless it flips to Failed.
Partial Success	Some of the requested transcript modules returned; others failed. Common when requesting multiple years and one year is unavailable.	Expand the row to see which modules failed. Re-queue just the failures if needed.
Succeeded	All requested transcripts returned and were saved to disk.	Open the client folder to review. Analyzers will pick up the new data automatically.
Failed	The request failed after exhausting retries. A specific error code is attached.	Click the row to see the error code, then look it up in the error table below.
Cancelled	You cancelled the request, or the batch was stopped before this row was sent.	Re-queue the request if you still want it.

Error codes & messages

When a request fails, TRH surfaces the specific error code on the row. Click any error below for details. If an error isn't listed, email us the full text and we'll add it.

Authentication errors

Error	What it means	Remediation
`IRSAuthError`	The IRS rejected the signed JWT in the A2A handshake. The token was either malformed, signed with the wrong key, or your A2A enrollment is inactive.	Open Tools & System → IRS Authentication and click Test Connection. Verify your Client ID, User ID, and Key ID match what's registered in e-Services. Confirm the private key file path is correct and the file is readable.
`Session Expired`	The cached A2A session token has aged out. Normal after long idle periods.	TRH should refresh the token automatically on the next request. If the error repeats, restart the dispatcher.

CAF & authority errors

Error	What it means	Remediation
`CAF Not Valid` / `CAF Mismatch`	The CAF number in your request doesn't match the one on file with your A2A credentials, or the CAF number is malformed.	Verify the CAF number in Firm Profile against your e-Services portal. CAF is exactly 9 digits. If the firm profile CAF is right, the mismatch is IRS-side — contact the e-Help Desk.
`CAF Not Provisioned`	Your CAF number has been issued but isn't yet active in the IRS transcript system.	CAF provisioning takes 4 to 6 weeks after IRS approval. There is no workaround — wait out the delay. Re-test weekly with Test Connection.
`No Authority on File`	The IRS has no valid Form 2848 or Form 8821 on file authorizing you to access this taxpayer's records.	File (or re-file) Form 2848 or 8821 for this taxpayer. Processing typically takes 5 to 10 business days once faxed. Then retry the pull.
`Authority Expired`	Your 2848 or 8821 for this taxpayer existed but has expired or been revoked.	File a fresh 2848 or 8821. If the taxpayer revoked authority, you'll need to re-establish the engagement before re-filing.
`Delegated User Access Revoked`	A delegated-user relationship tied to your A2A client was revoked by the IRS or by the primary CAF holder.	Contact the IRS e-Help Desk (866-255-0654) to understand the revocation reason, and if appropriate, re-submit the delegation request. TRH can't restore IRS-side access.

IRS HTTP errors

Error	What it means	Remediation
`IRS Error 401 — Unauthorized`	The IRS did not accept your token for this request. Often indistinguishable from `IRSAuthError` at the transport layer.	Run Test Connection. If the test passes but individual requests still return 401, the issue is usually CAF or authority-related — check the CAF and authority error rows above.
`IRS Error 403 — Forbidden (IRS blocked)`	The IRS is refusing the request. Either this specific taxpayer is not accessible to you, or your CAF has been temporarily blocked (often after a spike of 401s or a suspected abuse pattern).	Pause dispatches for a few hours. Confirm 2848/8821 is on file for the affected taxpayer. If 403 affects every client (not just one), stop dispatching and contact the IRS e-Help Desk before retrying.
`IRS Error 429 — Rate Limited`	You've exceeded the IRS's per-CAF rate limit.	Pause all dispatching for 24 to 48 hours. When you resume, lower concurrency in Tools & System → Dispatch Settings. Retrying sooner usually extends the throttle window.
`IRS Error 500 — Service Unavailable`	An IRS-side server error. The transcript service is temporarily down or degraded.	TRH retries transient 500s automatically. If every request is failing for 15+ minutes, check IRS e-Services status for a declared outage, then pause and retry later.

Taxpayer-side errors

Error	What it means	Remediation
`Information Mismatch`	The SSN, legal name, or date of birth you submitted doesn't match the IRS's records for this taxpayer.	Check the SSN digit-by-digit. Verify the legal name spelling with the client (hyphens, suffixes, maiden names). Confirm DOB. Recently-married clients are a common cause — the IRS may still have the maiden name.
`Taxpayer Not Found`	The IRS cannot locate any record matching the identifiers submitted.	Confirm the SSN is correct and that the taxpayer has ever filed a federal return. First-time filers won't have transcripts for years prior to their first filing.
`ID Theft Indicator on Account`	The IRS has placed an identity-theft marker on this account. A2A transcript access is usually blocked while the marker is active.	The taxpayer must work through IRS identity verification (IRS.gov ID verification tool or Form 14039). Once the IRS clears the marker, transcript pulls resume. Timeline is generally 3 to 6 months.
`Deceased Taxpayer Flag`	The IRS account is flagged as deceased. A2A pulls typically fail until fiduciary authority is established.	File Form 56 (Notice of Fiduciary Relationship) signed by the executor or personal representative, plus 2848 or 8821 from the same fiduciary. Retry the pull after the IRS processes Form 56.
`Transcript Not Available for Year`	The IRS has no transcript data for the year you requested. Either the taxpayer didn't file that year, or the transcript type isn't maintained that far back.	Confirm whether the taxpayer filed that year. Wage & Income and Return Transcripts are generally retained for the current year + 3 prior. For older years, file Form 4506.

Transport & session errors

Error	What it means	Remediation
`Network / Transport Error`	TRH couldn't complete the HTTPS connection to the IRS. Usually a local networking issue: DNS, proxy, firewall, or an offline internet connection.	Confirm you have internet. If you're on a corporate firewall, allowlist `*.irs.gov`. Check proxy settings in Windows. TRH retries these automatically; persistent failures mean the local network is the problem.
`Session Expired`	The cached IRS session token expired between retries.	TRH refreshes automatically. If the error repeats across every request, restart the dispatcher or the app.

Licensing errors

Error	What it means	Remediation
`Hardware ID Mismatch`	Your license is bound to a different machine fingerprint than the current one. Usually triggered by a motherboard swap, disk reimaging, or a major Windows reinstall.	Email support@taxhub-usa.com with your license key. We'll release the prior binding so you can re-activate on the current machine.
`License Inactive / Expired`	Your paid license has reached its 365-day expiration, or the licensing server has flagged it inactive (e.g. refunded, revoked).	Renew through the same checkout flow you used to purchase. If you believe the license should still be active, contact support with your license key.

Can't find your error?

Contact support@taxhub-usa.com with the full error text (copy it from the dispatch row or the log file at Tools & System → About → Open Logs) and we'll add it here.