← All how-to walkthroughs
Walkthrough 09 · 5 errors

Troubleshooting the 5
Most Common Errors

Ninety percent of failed transcript pulls come down to one of these five errors. Each card tells you what the error means, what caused it, and the two or three steps that fix it. For a deeper dive, follow the link at the bottom of each card.

Placeholder screenshots: every image block is a description of what the final annotated screenshot should show. Real screenshots with arrows and circles will be added before publish.
401
Unauthorized
SCREENSHOT 1.1 — 401 DIALOG
Shows: TRH error dialog with a red header bar. Title: "IRS returned 401 Unauthorized". Body: "Your IRS e-Services session is expired or your credentials were rejected." Two buttons: "Re-enter credentials" and "Open error guide".
Annotations:
  1. RED CIRCLE around the "401" code in the header
  2. YELLOW ARROW at "Re-enter credentials"
  3. GREEN CALLOUT: "Most 401s are a stale IRS UID — fix takes 60 seconds"

Cause

Your IRS e-Services session expired, or the username + UID stored in TRH no longer matches what IRS has on file. IRS rotates UIDs periodically and forces a re-login after ~15 minutes of idleness.

Fix

  1. Open Settings → IRS Connection and click Re-enter credentials. Type the username exactly as it appears in e-Services.
  2. Log into e-Services in a browser, copy the current UID from your profile, paste it back into TRH.
  3. Click Test connection. A green check means you're good; try the transcript pull again.
Read the full 401 article →
403
IRS Blocked
SCREENSHOT 2.1 — 403 DIALOG
Shows: TRH error dialog. Title: "IRS returned 403 Forbidden". Body: "IRS recognized your credentials but refused the request — most likely an IP or user-agent block, or no active CAF authorization for this taxpayer." Buttons: "Check CAF", "Open error guide".
Annotations:
  1. RED CIRCLE around the "403" code
  2. YELLOW ARROW at the "Check CAF" button
  3. GREEN CALLOUT: "403 ≠ 401 — your login worked, but something else blocked the request"

Cause

Your login worked — IRS just refused this particular request. Three common sub-causes: (1) no active CAF authorization for the taxpayer, (2) your outbound IP is on an IRS deny-list (rare; usually a shared VPN), (3) you're hitting the API from an unexpected user-agent after an IRS-side update.

Fix

  1. Open the client and confirm the 2848 or 8821 shows CAF-confirmed. If still "Submitted", the authorization hasn't posted to CAF yet — wait 48 hours.
  2. If you're on a VPN, disconnect and retry. Shared residential VPNs are sometimes IP-blocked by IRS e-Services.
  3. If neither of the above applies, go to Help → Check for Updates. A TRH update usually ships within hours of an IRS-side API change that causes a 403.
Read the full 403 article →
429
Rate Limited
SCREENSHOT 3.1 — 429 DIALOG
Shows: TRH error dialog. Title: "IRS returned 429 Too Many Requests". Body: "You're pulling faster than the IRS rate limit allows. TRH paused the queue for 10 minutes." Countdown timer "Resumes in 9:42". Button: "Pause queue" / "Resume now".
Annotations:
  1. RED CIRCLE around the "429" code
  2. YELLOW ARROW at the countdown timer
  3. GREEN CALLOUT: "TRH handles this automatically — no action required, just wait"

Cause

You (or your firm) exceeded the IRS per-CAF rate limit. IRS has undocumented ceilings around ~80 transcripts per hour per CAF number. Firms with multiple practitioners sharing a single CAF hit this during busy season.

Fix

  1. Wait. TRH paused the queue automatically and will resume when the window opens. The countdown timer shows when.
  2. If you're in a hurry, split the workload: have a colleague with a different CAF number pull the next batch.
  3. Recurring 429s mean your firm is under-provisioned on CAF numbers. Add a second CAF in Settings → Firm Profile → Multi-CAF and TRH will round-robin.
Read the full 429 article →
CAF
CAF Not Valid
SCREENSHOT 4.1 — CAF-INVALID DIALOG
Shows: TRH error dialog. Title: "CAF authorization not valid for this taxpayer". Body explains the 2848/8821 didn't post, was rejected, or has been revoked. Buttons: "View authorization", "Re-file 2848", "Open error guide".
Annotations:
  1. RED CIRCLE around the error title
  2. YELLOW ARROW at "Re-file 2848"
  3. GREEN CALLOUT: "This is the most common transcript error in practice"

Cause

IRS has no active authorization on file linking you to this taxpayer. Either the 2848/8821 was never submitted, it was rejected silently (common for stale CAF numbers or missing spousal signature), or the taxpayer revoked it.

Fix

  1. Open the client's Authorizations tab. If the status isn't CAF-confirmed, that's your problem — it never posted.
  2. Call the IRS Practitioner Priority Service line with the client on three-way or with a 2848 in hand to ask what's on file. They can see rejection reasons you can't.
  3. Regenerate and re-file. See 05 — Generate 2848/8821 for the full walkthrough.
Read the full CAF article →
MISMATCH
Information Mismatch
SCREENSHOT 5.1 — MISMATCH DIALOG
Shows: TRH error dialog. Title: "Information doesn't match IRS records". Body: "The taxpayer's name, SSN, or address on file with TRH does not match what IRS has on file." A highlighted diff shows "TRH: 123 Main St" vs "IRS: 125 Main Street". Buttons: "Edit client info", "Open error guide".
Annotations:
  1. RED CIRCLE around the diff showing the address mismatch
  2. YELLOW ARROW at "Edit client info"
  3. GREEN CALLOUT: "Almost always an address or middle-initial issue — IRS is strict"

Cause

At least one of these fields in TRH doesn't exactly match what the IRS has on file: legal name (including middle initial), SSN/EIN, or the most recent address on the last filed return. IRS compares character-by-character. "Street" and "St." are different.

Fix

  1. Ask the client for a copy of their last filed return. The name and address exactly as shown there is what IRS expects.
  2. Edit the client record in TRH to match — including abbreviations. "Street" must be "Street", not "St.", if that's what's on the return.
  3. If the client moved, they need to file Form 8822 (change of address) with IRS and wait ~6 weeks before the new address is on file. Until then, use the old address in TRH.
Read the full mismatch article →
Not legal or tax advice. This content is published by Tax Resolution Hub for educational use by tax professionals. It is not legal, tax, accounting, or investment advice, and does not create an attorney-client or preparer-client relationship. IRS systems, forms, procedures, and statutes change — always verify against current IRM guidance, the client's actual transcript, and the facts of the specific engagement before acting.