HMRC MTD Error Codes: What They Mean and How to Fix Them
Hit an HMRC MTD error code mid-submission? Here's what each code actually means, why it happens, and exactly how to fix it without calling HMRC.
Your quarterly MTD submission was due yesterday. You clicked send, waited, and got back a cryptic string: CLIENT_OR_AGENT_NOT_AUTHORISED. No explanation. No fix. Just a code that reads like a password reject from 1997.
HMRC MTD error codes are the silent tax penalty nobody budgets for: not in money, but in time, stress, and missed deadlines. This post names every common code, explains what actually triggered it, and tells you what to do next before HMRC's clock starts ticking.
- HMRC MTD error codes fall into five broad categories: authorisation, validation, throttling, business rules, and server-side faults.
- Most errors are fixable without calling HMRC if you know which field or setting caused them.
- A submission that fails silently (no acknowledgement) still counts as not filed; your deadline does not pause.
- Software like TapTax surfaces plain-English explanations alongside the raw code so you are not left guessing.
- Keeping a record of each error and its resolution protects you if HMRC ever disputes a late-filing claim.
- HMRC MTD Error Code
- A machine-readable response code returned by HMRC's Making Tax Digital API when a submission is rejected or cannot be processed. Codes follow HTTP status conventions (400, 401, 403, 422, 429, 500) and are accompanied by a short message string that identifies the specific rule that failed.
Why HMRC's Error Messages Read Like Morse Code
MTD runs on a REST API. When your software sends a submission to HMRC, HMRC's servers respond with a status code and a message payload. The problem is that HMRC designed this system for software developers, not for a self-employed decorator sitting at a kitchen table at 9pm wondering why their return just bounced.
Software vendors are supposed to translate these codes into plain English before displaying them to users. Some do. Many do not, or they bury the explanation behind a generic "something went wrong" message and a link to a help page that, with quiet irony, also tells you nothing useful.
The result: sole traders Google the raw error string, find a three-year-old developer forum post, and give up. That is how a fixable two-minute problem turns into a missed deadline and a £100 penalty from HMRC.
If you have already fallen foul of a late filing penalty and want to understand what it actually costs, HMRC Late Filing Penalty: What Self Assessment Really Costs runs the numbers.
The Five Families of MTD Error Codes
Before we go code by code, it helps to know that HMRC groups its errors by HTTP status class. Once you know which class you are dealing with, you already know whether the problem is on your side, HMRC's side, or your software's side.
400 Errors: Your Submission Has a Data Problem
A 400 response means HMRC's API rejected your submission at the door. The data you sent failed one of HMRC's validation rules before any tax calculation took place.
INVALID_REQUEST is the broadest 400 error. It means a required field is missing, formatted incorrectly, or contains a value outside the permitted range. Common causes: income figures entered as text rather than numbers, a negative turnover figure, or a submission period date that does not match HMRC's records for your business. Check every numeric field carefully. If you are using bridging software with a spreadsheet, a merged cell or formula error is the usual culprit.
INVALID_TAX_YEAR appears when the tax year in your submission does not match a period HMRC recognises for your MTD account. This often happens when someone tries to submit a period that begins before their MTD start date. If you registered for MTD mid-year, your first valid submission period is from your sign-up date, not from 6 April.
INVALID_INCOME_SOURCE_ID is particularly confusing. Every income source you have under MTD (self-employment, property income, etc.) is assigned a unique ID by HMRC when you register. If your software sends the wrong ID, or if you have reset your MTD registration without updating your software's stored IDs, this error fires. Fix: log into your MTD-compatible software and re-pull your income source IDs from HMRC's API. In TapTax, this happens automatically at login.
RULE_INCORRECT_OR_EMPTY_BODY means the JSON body of the request was either blank or structured incorrectly. This is almost always a software bug or a failed export from a spreadsheet. Contact your software provider rather than HMRC.
401 and 403 Errors: The Authorisation Maze
These are the most frustrating errors because they feel personal: HMRC is telling you it does not recognise you. They are almost never caused by anything the user did wrong in the last session.
UNAUTHORIZED (note: HMRC uses the American spelling in its API) means your OAuth token has expired. MTD uses a token-based authentication system. Tokens are valid for 18 months from when you first authorised your software. After that, you must re-authorise. Fix: go to your software's settings and look for a "reconnect to HMRC" or "re-authorise" option. You will be redirected to the HMRC Government Gateway login, and your token will be refreshed.
CLIENT_OR_AGENT_NOT_AUTHORISED is the most Googled MTD error code in the UK, and for good reason. It fires in three situations: you are trying to submit before HMRC has finished processing your MTD registration (HMRC says allow 72 hours, but backlogs have stretched this to two weeks); your software's client ID does not match HMRC's record for your UTR; or, if you use an accountant, your agent has not been granted the correct MTD authorisation permissions. The fix depends on which of these three applies. Wait 72 hours first. If it persists, check with your software provider that your UTR is correctly stored. If you use an agent, ask them to verify their agent services account permissions.
AGENT_NOT_AUTHORISED is the agent-specific variant. It means your accountant's software is correctly registered as an agent but has not been granted authorisation for your specific MTD account. Your accountant needs to submit a new authorisation request through HMRC's agent services portal and you need to approve it via your Government Gateway account.
If you have had broader problems with your MTD setup beyond error codes, Making Tax Digital Problems Nobody Warned You About covers the wider landscape of things that go wrong at the registration stage.
422 Errors: Business Rule Violations
A 422 (Unprocessable Entity) means the data was technically valid but violates one of HMRC's business rules. These are among the hardest to diagnose because HMRC's business rule logic is not always publicly documented.
RULE_SUBMISSION_FAILED_DUE_TO_ALREADY_BEING_ACCEPTED sounds alarming. It means you are trying to submit a period that HMRC already has a successful submission for. This happens when your software submitted successfully but failed to display the confirmation to you, so you tried again. Check your submission history inside your software before re-submitting. If no history exists, call HMRC's MTD helpline (0300 200 3310) and ask them to confirm whether the period is showing as received.
RULE_INCORRECT_CONSOLIDATION_BASIS relates to property income and appears when the method of accounting stated in your submission does not match your registration details. If you have rental income alongside self-employment, check your Making Tax Digital for Landlords 2026: Are You Ready? obligations separately.
RULE_OUTSIDE_AMENDMENT_WINDOW means you are trying to amend a submission for a period that HMRC has closed for amendments. Amendments are generally allowed within 12 months of the original filing date. After that, you need to contact HMRC directly.
429 Errors: You Hit HMRC's Rate Limit
TOO_MANY_REQUESTS is an error most sole traders never see unless their software has a bug that triggers repeated API calls. HMRC throttles the number of requests any software client can make per second. If you see this error, wait five to ten minutes and try again. If it recurs, your software may be stuck in a retry loop; log out completely, clear the app cache if the option exists, and try a fresh submission.
500 Errors: HMRC's Servers Are Having a Moment
INTERNAL_SERVER_ERROR and SERVICE_UNAVAILABLE (503) mean the fault is on HMRC's side, not yours. HMRC publishes a service availability dashboard at https://www.tax.service.gov.uk/self-assessment/ind/ but its real-time accuracy is, diplomatically, inconsistent. If you receive a 500 or 503 error, take a screenshot with the timestamp, note it in your records, and retry in two to four hours. If the outage persists close to your deadline, HMRC's policy is that genuine server-side failures do not trigger penalties, but you will need that evidence.
The Error Nobody Mentions: The Silent Non-Submission
The most dangerous MTD error is the one that produces no error code at all. Some software shows a spinning loader, times out, and returns you to the dashboard without any confirmation. You assume it went through. It did not.
HMRC's API has a timeout threshold. If your submission takes longer than the permitted window (due to connection issues or HMRC server load), the API drops the connection without sending a response. Your software may not handle this gracefully.
The fix: always check your submission history inside your software after every quarterly update. Look for a reference number or an acknowledgement timestamp. If neither appears, your submission has not been received. Re-submit immediately.
How to Protect Yourself When Errors Happen Near Deadlines
Every sole trader using MTD should have a short emergency protocol. Here is what it looks like in practice for, say, a handyman with a turnover of £55,000 who gets a CLIENT_OR_AGENT_NOT_AUTHORISED error on the evening their Q3 submission is due.
Step one: screenshot the full error message including the timestamp and any reference numbers shown by the software. This is your evidence if you later need to argue against a penalty.
Step two: check HMRC's service availability page and your software provider's status page. If either shows an incident, document it.
Step three: try the submission again 30 minutes later. For auth errors, try re-authorising first.
Step four: if you cannot resolve it by the deadline, email HMRC's MTD support (details via your Government Gateway account) with your screenshot attached, stating the error code, the period in question, and the time of your first attempt. HMRC does exercise discretion where there is clear evidence of a good-faith attempt.
Step five: keep a record. HMRC's penalty points system for MTD, which replaces the flat £100 fine for missed submissions, is designed to distinguish between chronic non-filers and people who hit genuine technical problems. A paper trail is the difference between a warning and a charge.
For a full breakdown of how the MTD penalty points regime works alongside broader filing mistakes, MTD Common Mistakes Sole Traders Make Before Filing is worth reading before your next submission window opens.
Why Your Software's Error Handling Matters More Than the Code
The MTD API specification is public. Every software vendor building an MTD product has access to the same list of error codes and their definitions. The quality gap between products is not in the data; it is in what the software does with that data before showing it to a sole trader who just wants to file and get on with their day.
Good MTD software does three things when an error fires: it translates the code into plain English, it tells you specifically which field or setting caused the problem, and it offers a direct path to the fix. Poor MTD software shows you the raw code and a generic support link.
If your current software regularly leaves you staring at strings like INVALID_INCOME_SOURCE_ID at 10pm, that is a product failing, not a you failing. Accounting Software for Freelancers UK: Stop Paying for Features You'll Never Use covers how to evaluate whether your software is actually working for you.
If you are considering switching without losing your submission history or records, How to Switch to MTD Software Without Losing a Day's Work walks through that process step by step.
People also ask
A Quick Reference: The Eight Codes Every Sole Trader Should Know
To save you Googling at midnight:
INVALID_REQUEST(400): A field is wrong, empty, or formatted incorrectly. Check every figure.INVALID_TAX_YEAR(400): The submission period predates your MTD start date.INVALID_INCOME_SOURCE_ID(400): Reconnect your software to refresh your income source IDs.UNAUTHORIZED(401): Your OAuth token has expired. Re-authorise via Government Gateway.CLIENT_OR_AGENT_NOT_AUTHORISED(403): Registration still processing, expired token, or agent permissions issue.RULE_SUBMISSION_FAILED_DUE_TO_ALREADY_BEING_ACCEPTED(422): You already filed this period. Check your submission history.TOO_MANY_REQUESTS(429): Wait ten minutes and retry. Contact your software provider if it recurs.INTERNAL_SERVER_ERROR(500): HMRC's problem, not yours. Screenshot, wait, retry. Keep evidence.
The Error Code That Started This Article
CLIENT_OR_AGENT_NOT_AUTHORISED. That cryptic string, returned to thousands of sole traders who did nothing wrong except register for a government digital service, is a reasonable metaphor for the entire MTD project: a system designed by developers, for developers, deployed on people who just want to pay the right tax and get back to work.
Knowing the codes does not fix the system. But it does mean the next time HMRC's API bounces your submission, you will spend two minutes resolving it rather than two hours panicking, and you will have the evidence you need if the deadline slips regardless.
You might also like
Ready to simplify your tax filing?
Join the waitlist and be the first to know when TapTax launches.