Skip to main content
All Docs
FeaturesMaking Tax DigitalUpdated March 31, 2026

HMRC Connection Errors & Reconnecting Your Account

HMRC Connection Errors & Reconnecting Your Account

This page explains what happens when your HMRC OAuth connection expires or is revoked, how the platform handles it, and what steps to take to restore your connection.

How HMRC OAuth tokens work

When you connect your HMRC account, the platform stores an access token (short-lived) and a refresh token (longer-lived). Before each submission the platform automatically uses the refresh token to obtain a new access token — you normally never need to reconnect manually.

If the refresh token itself expires or is revoked (for example, because you disconnected the app from your HMRC Government Gateway account, or HMRC invalidated the session), the automatic refresh will fail and no valid token can be obtained.

What happens when the token cannot be refreshed

As of v1.0.475, the platform distinguishes between two types of failure:

Permanent auth failures (401 / 403 / invalid_grant / token_revoked)

  • The platform immediately stops the submission attempt.
  • The credential is marked as expired in the system — no further retry attempts are made.
  • The submission is recorded with a status of failed (not rejected).
  • A clear notification is shown: "Please reconnect your HMRC account".

Transient failures (network errors, HMRC 5xx)

  • The platform re-throws the error so Inngest can automatically retry the step with exponential backoff.
  • The credential is not marked as expired.
  • No action is needed from you unless retries are exhausted.

Submission statuses explained

StatusMeaning
submittedHMRC accepted the submission successfully.
failedThe submission could not be sent — typically an auth or connectivity issue. Reconnect your HMRC account and resubmit.
rejectedHMRC received the submission but refused the figures (e.g. validation errors in your data). Review and correct the flagged figures, then resubmit.
processingThe submission is currently in progress.

Important: Before v1.0.475, expired-token failures were incorrectly stored as rejected, making it appear that HMRC had refused your figures. If you saw rejected submissions before this release that seemed unexplained, they may have been auth failures. Reconnect your HMRC account and resubmit those periods.

How to reconnect your HMRC account

  1. Navigate to Settings → HMRC Connection.
  2. Click Reconnect HMRC Account.
  3. You will be redirected to the HMRC Government Gateway sign-in page.
  4. Sign in and grant the requested permissions.
  5. You will be redirected back to the platform with a fresh set of tokens.
  6. Return to the affected submission and click Resubmit.

Affected submission types

The improved error handling applies to all HMRC submission flows:

  • Quarterly period submissions — fetch-obligations and submit-period steps.
  • Annual summary — submit-annual-summary step.
  • End of Period Statement (EOPS) — submit-eops step.
  • Crystallisation (final declaration) — submit-crystallisation step.