HMRC Error Codes and What They Mean
If you see an error when using Aligned, find the error code below for an explanation and what to do next. Most errors can be resolved without contacting support.
Errors are grouped by category to help you find the right one quickly.
1. Connection and authorisation errors
These errors mean there is a problem with your connection to HMRC or your permissions.
| Error code | What it means | What to do |
|---|---|---|
| UNAUTHORIZED | Your connection to HMRC may have expired or you do not have permission. | Click “Reconnect to HMRC” to sign in again. Make sure you are using the right HMRC account. If you are an agent, check you are authorised for this client. Try signing out completely and signing in again. |
| CLIENT_OR_AGENT_NOT_AUTHORISED | You do not have permission to access this information. | Check you are signed in with the correct HMRC account. If you are an agent, verify your client authorisation is active. Try reconnecting to HMRC. Contact HMRC if you should have access. |
| FORBIDDEN | You do not have the necessary permissions for this action. | Check you are using the correct HMRC account. Verify your Making Tax Digital registration is active. If you are an agent, confirm your authorisation is current. Contact HMRC to request the necessary permissions. |
2. Format and validation errors
These errors mean the data you sent is not in the format HMRC expects.
| Error code | What it means | What to do |
|---|---|---|
| FORMAT_NINO | The National Insurance Number format is not correct. | Check the format is AA123456A (2 letters, 6 numbers, 1 letter). Remove any spaces or hyphens. Make sure you are using the right NINO for this person. |
| FORMAT_TAX_YEAR | The tax year format is not correct. | Use the format YYYY-YY (for example, 2025-26). Make sure the year range is valid (second year should be first year + 1). Check you have selected the correct tax year from the dropdown. |
| FORMAT_VALUE | One of the amounts is not in the right format. | Use numbers only, up to 2 decimal places. Do not include currency symbols or commas. Make sure all amounts are within the allowed range. |
| FORMAT_FROM_DATE | The period start date format is not correct. | Use the format YYYY-MM-DD (for example, 2025-04-06). Make sure the date is valid. Check the date matches the obligation period. |
| FORMAT_TO_DATE | The period end date format is not correct. | Use the format YYYY-MM-DD (for example, 2025-07-05). Make sure the date is valid. Check the date matches the obligation period. |
| FORMAT_START_DATE | The period start date format is not correct. | Use the format YYYY-MM-DD (for example, 2025-04-06). Make sure the date is valid. Check the date falls within the correct tax year. |
| FORMAT_END_DATE | The period end date format is not correct. | Use the format YYYY-MM-DD (for example, 2025-07-05). Make sure the date is valid. Check the date falls within the correct tax year. |
| FORMAT_BUSINESS_ID | The business ID format is not correct. | Business IDs should be exactly 15 characters. Check you have copied the full ID from HMRC. Try refreshing your business list from HMRC. |
| FORMAT_CALCULATION_ID | The calculation ID format is not correct. | Calculation IDs should be in UUID format. Try triggering a new calculation. Check you are using the most recent calculation. |
| FORMAT_COUNTRY_CODE | The country code for one of your properties is not in the correct format. | Use a 3-letter ISO country code (e.g., FRA for France, ESP for Spain). Common codes: USA, CAN, AUS, DEU (Germany), ITA, PRT (Portugal). Remove any spaces or special characters. |
| FORMAT_PROPERTY_ID | The property ID format is not correct. | Property IDs are assigned by HMRC when you create a property. Check you have copied the full property ID correctly. Try refreshing your property list from HMRC. |
| FORMAT_PROPERTY_NAME | The property name you provided is not valid. | Property names must be between 1 and 105 characters. Remove any special characters that might cause issues. Make sure the name is descriptive and unique for each property. |
| FORMAT_PROPERTY_END_DATE | The property end date format is not correct. | Use the format YYYY-MM-DD (for example, 2025-12-31). Make sure the date is valid and within the tax year. If ending a property, you must also provide an end reason. |
| FORMAT_END_REASON | The reason for ending the property is not valid. | Use one of these values: “no-longer-renting-property-out”, “disposal”, or “added-in-error”. If ending a property, you must also provide an end date. Make sure the spelling is exactly correct. |
| RULE_INCORRECT_OR_EMPTY_BODY_SUBMITTED | The data you submitted does not meet HMRC’s requirements. | Check all required fields are filled in. Verify your amounts are in the correct format. Make sure you are using the right template. Review any validation warnings before submitting. |
3. Business rule errors
These errors mean your submission breaks one of HMRC’s business rules - usually about timing, periods, or business registration.
| Error code | What it means | What to do |
|---|---|---|
| RULE_ALREADY_EXISTS | A submission for this period already exists in HMRC’s records. | Check your submission history to see what was submitted. If you need to make changes, you can amend the existing submission. Contact HMRC if you believe this is an error. |
| MATCHING_RESOURCE_NOT_FOUND | HMRC could not find this business in their records. | Check the business is registered for Making Tax Digital. Try refreshing your business list from HMRC. Make sure you are signed in with the correct HMRC account. |
| RULE_BUSINESS_ID_NOT_FOUND | HMRC could not find this business ID in their records. | Refresh your business list from HMRC. Check you are using the correct HMRC account. Make sure the business is registered for Making Tax Digital. |
| RULE_TAX_YEAR_NOT_SUPPORTED | This tax year is not available for submission yet. | Check which tax years are currently open for submissions. Make sure you are selecting the correct year. HMRC usually opens submissions for a tax year from 6 April. |
| RULE_TAX_YEAR_NOT_ENDED | You cannot submit for a tax year that has not finished yet. | Wait until the tax year ends (5 April). Check you have selected the correct tax year. For quarterly updates, you can submit during the year. |
| RULE_TAX_YEAR_RANGE_INVALID | The tax year range does not match HMRC’s expected format. | Tax years must span exactly one year (e.g., 2025-26). Check you have selected the correct tax year. The second year must be exactly one more than the first. |
| RULE_OUTSIDE_AMENDMENT_WINDOW | This submission is outside the allowed time window for amendments. | Check the amendment deadline for this period. Contact HMRC if you need to make changes after the deadline. Keep records of what you tried to amend. |
| RULE_FINAL_DECLARATION_RECEIVED | You have already submitted your Final Declaration for this tax year. | You cannot submit another Final Declaration for the same year. Contact HMRC if you need to make changes. Check you are working on the correct tax year. |
| RULE_END_DATE_BEFORE_START_DATE | The period end date is earlier than the start date. | Check the start and end dates are the right way round. Make sure you have selected the correct obligation period. Verify the dates match your HMRC obligation. |
| RULE_EARLY_DATA_SUBMISSION_NOT_ACCEPTED | HMRC is not accepting submissions for this period yet. | Wait until the submission window opens for this period. Check the obligation start date - you can only submit once it is active. Try submitting closer to or after the period start date. |
| RULE_ADVANCE_SUBMISSION_REQUIRES_PERIOD_END_DATE | An advance submission must include the period end date. | Include both a start date and end date in your submission. Check the obligation details for the correct end date. Make sure dates are in YYYY-MM-DD format. |
| RULE_START_DATE_NOT_ALIGNED_WITH_REPORTING_TYPE | The start date does not align with your chosen reporting frequency (quarterly or annual). | Check the start date matches your obligation period. Quarterly periods must start on the correct quarter boundary. Verify your reporting type in HMRC’s records. |
| RULE_START_DATE_NOT_ALIGNED_TO_COMMENCEMENT_DATE | The period start date does not align with the date your business started trading. | Check when your business was registered with HMRC. The first period must start on your business commencement date. Contact HMRC if the commencement date on record is wrong. |
| RULE_END_DATE_NOT_ALIGNED_WITH_REPORTING_TYPE | The end date does not align with your chosen reporting frequency (quarterly or annual). | Check the end date matches your obligation period. Quarterly periods must end on the correct quarter boundary. Verify your reporting type in HMRC’s records. |
| RULE_MISSING_SUBMISSION_DATES | The submission is missing the required start or end date. | Make sure both start and end dates are included. Check the obligation details for the correct dates. Dates must be in YYYY-MM-DD format. |
| RULE_START_AND_END_DATE_NOT_ALLOWED | Start and end dates should not be provided for this type of submission. | Remove the start and end dates from your submission. This submission type does not require explicit dates. Check HMRC guidance for the correct submission format. |
| RULE_SUBMISSION_FAILED | HMRC could not process your submission due to a technical issue. | Wait a few minutes and try again. Check all your data is valid. If the problem continues, contact HMRC support. Save a copy of your data before retrying. |
| RULE_DUPLICATE_SUBMISSION | A submission for this exact period has already been sent to HMRC. | Check your submission history - this period may already be submitted. If you need to update the figures, use the amend option instead. Make sure you are not submitting the same period twice. |
| RULE_TYPE_OF_BUSINESS_INCORRECT | The business ID does not match the type of property business you are trying to submit. | Check you have selected the correct business from your list. UK property and foreign property are separate business types. Refresh your business list from HMRC. |
| RULE_TO_DATE_BEFORE_FROM_DATE | The period end date is earlier than the start date. | Check the start and end dates are the right way round. Make sure you have selected the correct obligation period. Verify the dates match your HMRC obligation. |
| RULE_OVERLAPPING_PERIOD | This submission overlaps with a period you have already submitted to HMRC. | Check your submission history to see which periods are already submitted. If you need to change an existing submission, use the amend option instead. Make sure you are not submitting the same period twice. |
| RULE_MISALIGNED_PERIOD | The submission period does not fall within your accounting period. | Check the dates against your obligation period from HMRC. Make sure the period is within your business’s accounting year. Verify you have selected the correct tax year. |
| RULE_NOT_CONTIGUOUS_PERIOD | Your period summaries have gaps between them. HMRC requires continuous periods with no gaps. | Check for any missing periods between your submissions. Submit data for any gap periods. Make sure each period starts the day after the previous period ends. |
| RULE_COUNTRY_CODE | The country code for one of your properties is not a valid ISO 3166-1 alpha-3 country code. | Use a valid 3-letter ISO country code (e.g., FRA for France, ESP for Spain). Check your spreadsheet for typos in the country code. |
| RULE_DUPLICATE_COUNTRY_CODE | You have submitted the same country code for multiple properties. | HMRC requires you to combine all properties in the same country into one entry. Add up the totals for all properties in the same country. Remove any duplicate country entries. |
| RULE_DUPLICATE_PROPERTY_NAME | This property name already exists for the same country. | Choose a different name for this property. Names are case-insensitive (e.g., “Paris Flat” and “paris flat” are considered the same). Add identifying details to make the name unique. |
| RULE_TAX_YEAR_BEFORE_BUSINESS_START | You are trying to submit for a tax year before your property business started trading. | Check when your property business was first registered with HMRC. Make sure you are selecting the correct tax year. You can only submit from the tax year your business started. |
| RULE_END_DATE_BEFORE_TAX_YEAR_START | The property end date you provided is before the start of the tax year. | Check the end date is within the tax year you are submitting for. Tax years run from 6 April to 5 April. Make sure you have selected the correct tax year. |
| RULE_END_DATE_AFTER_TAX_YEAR_END | The property end date you provided is after the end of the tax year. | Check the end date is within the tax year you are submitting for. Tax years end on 5 April. Make sure you have selected the correct tax year. |
| RULE_PROPERTY_BUSINESS_CEASED | This property business income source has ended, so you cannot submit new data for it. | Check if you accidentally marked this property as ceased. You can only submit data for active properties. If you need to re-enable the property, contact HMRC. |
| RULE_MISSING_END_DETAILS | If you are ending a property, you must provide both an end date and an end reason. | Provide both an end date (YYYY-MM-DD) and an end reason. End reasons: “no-longer-renting-property-out”, “disposal”, or “added-in-error”. Leave both fields empty if the property is still active. |
| NOT_FOUND | HMRC could not find the record you requested. | Check the ID or reference is correct. Make sure the record exists in HMRC’s system. Try refreshing your data from HMRC. You may need to create the record first. |
| NO_DATA_FOUND | HMRC has no data for this request. | Submit your income data first. Make sure you are checking the correct period. Verify your business is registered with HMRC. Check you have selected the correct tax year. |
4. Submission and calculation errors
These errors relate to problems with the content of your submission or tax calculation.
| Error code | What it means | What to do |
|---|---|---|
| RULE_BOTH_EXPENSES_SUPPLIED | Your submission includes both consolidated expenses and individual expense categories. | Choose either consolidated (single total) or detailed (individual categories). If your turnover is under 90,000, you can use consolidated. If 90,000 or more, you must use detailed categories. Remove the expense type you do not want and re-upload. |
| RULE_NOT_ALLOWED_CONSOLIDATED_EXPENSES | You cannot use consolidated expenses because your turnover exceeds the 90,000 threshold. | Use detailed expense categories instead of a single consolidated figure. Break down your expenses into individual categories (e.g., office costs, travel). Update your spreadsheet to use detailed categories and re-upload. |
| RULE_NO_INCOME_SUBMISSIONS_EXIST | HMRC has no income data for this period yet. | Submit your quarterly income data first. Make sure you are checking the correct period. Allow a few minutes after submission for HMRC to process. |
| RULE_CALCULATION_ERROR_MESSAGES_EXIST | There are errors in your tax calculation that need fixing. | View the calculation details to see specific errors. Fix the issues in your submission. Submit corrected data and trigger a new calculation. |
| RULE_ALREADY_ADJUSTED | This summary has already been adjusted. | Check if adjustments were made previously. You may need to create a new adjustment. Contact HMRC if you need to make further changes. |
| RULE_RESULTING_VALUE_NOT_PERMITTED | The calculation result is not permitted by HMRC rules. | Check your income and expense amounts. Make sure adjustments are within allowed ranges. Review HMRC guidance for this calculation. |
| RULE_PERIODIC_DATA_INCOMPLETE | Your quarterly update data is missing required information. | Check all required fields are filled in. Make sure you have submitted all previous quarters. Complete any missing periods before this one. |
| RULE_INCORRECT_GOV_TEST_SCENARIO | The test scenario specified is not valid (sandbox only). | Check you are using a valid Gov-Test-Scenario header. This error only appears in the sandbox environment. Review HMRC’s test scenario documentation. |
5. Server and system errors
These errors mean HMRC is having technical problems. They are usually temporary.
| Error code | What it means | What to do |
|---|---|---|
| SERVER_ERROR | HMRC is experiencing technical difficulties. | Wait 15-30 minutes and try again. Check the HMRC service status page. Your data has been saved - you will not lose your work. Contact HMRC support if the issue continues. |
| SERVICE_UNAVAILABLE | The HMRC service is temporarily unavailable. | This is usually a temporary issue. Wait 15-30 minutes and try again. Check the HMRC service status page. Try again later if the service is down for maintenance. |
| TOO_MANY_REQUESTS | You have made too many requests to HMRC in a short time. | Wait a minute before trying again. Avoid clicking submit multiple times. The request limit resets after a few minutes. |
Still stuck?
If you cannot find your error code above, or the suggested steps do not resolve the issue:
- Check the full error message - Aligned shows the complete HMRC response, which may include more detail than the error code alone
- Try again later - Some errors are temporary, especially server and system errors
- Contact HMRC - For persistent errors related to your tax data or registration, HMRC’s helpline can investigate
- Contact Aligned support - If you believe the error is a software issue rather than an HMRC issue