HMRC Connection Troubleshooting

This page covers common errors related to the HMRC OAuth connection and token lifecycle, and explains what happens when your authorisation expires.

"HMRC Authorisation Required" notification

If you see an in-app notification with the title "HMRC Authorisation Required" after a quarterly submission attempt, it means your HMRC OAuth session has expired and could not be automatically renewed.

Why this happens

The platform uses a short-lived access token (typically 4 hours) to authenticate requests to HMRC. When this token expires, it is automatically refreshed using a refresh token stored securely in the platform.

The notification is shown when:

• The refresh token itself has expired (HMRC refresh tokens have a finite lifetime).
• The refresh token was revoked — for example, because you re-authorised in another session or your HMRC credentials changed.
• The HMRC authorisation server returned an error during the refresh attempt.

Once any of these occur, automatic renewal is no longer possible and the platform cannot submit data to HMRC on your behalf until you reconnect.

What to do

1. Navigate to Dashboard → HMRC (or follow the link in the notification).
2. You will see a reconnect prompt on the HMRC connection page — the platform marks your credential status as expired immediately when refresh fails.
3. Click Reconnect HMRC account and complete the OAuth flow.
4. Once reconnected, re-trigger your quarterly submission from the submission page.

Note: Any submission that failed due to an expired credential will have its status set to failed with a clear error message. It will not be retried automatically — you must re-trigger it manually after reconnecting.

How token refresh works

Submission triggered
        │
        ▼
getValidCredentials()
        │
        ├─ Token still valid? ──────────────────────► proceed with submission
        │
        ├─ Token expired / expiring soon?
        │         │
        │         ▼
        │   refreshAccessToken()
        │         │
        │         ├─ Refresh succeeded? ────────────► persist new tokens, proceed
        │         │
        │         └─ Refresh failed?
        │                   │
        │                   ▼
        │           throw TokenRefreshError
        │                   │
        │                   ▼
        │           mark credential "expired"
        │           record DB failure
        │           send in-app notification
        │           write audit log
        │           return (non-retryable)
        │
        └─ No credentials found? ─────────────────► NonRetriableError

Audit log

Every credential failure during a submission is recorded in the audit log with the action hmrc.submission.credential_failure. Each entry includes:

Field	Value
action	hmrc.submission.credential_failure
resourceType	quarterly_summary
resourceId	The quarterly summary ID
metadata.reason	Human-readable failure reason
metadata.taxYear	The affected tax year
metadata.quarterPeriod	The affected quarter

You can review these entries in the audit log section of your dashboard.

Error reference

Error	Cause	Action required
HMRC Authorisation Required notification	Refresh token expired or revoked	Reconnect at /dashboard/hmrc
No HMRC credentials found	OAuth flow never completed	Complete HMRC authorisation
Generic API error during submission	Transient HMRC API issue	Retry the submission

Submission status after a credential failure

When a submission fails due to a credential error, the quarterly summary record is updated as follows:

status    → "failed"
lastError → "Your HMRC authorisation has expired. Please reconnect your HMRC
             account from the HMRC settings page before retrying this submission."

The submission will not be automatically retried. Re-trigger it manually once you have reconnected your HMRC account.