A failed request returns an errorCode and an errorMessage. Branch on errorCode, which never changes, rather than on the message text. Authentication failures are the exception and return {"detail": "..."}. This is part 2 of 2 of the list, generated from the API reference, version 0.5.0. It covers: Payrun, Pensions, RTI, Statutory documents, Webhooks, Working patterns.
Payrun
| Code | Default message | Raised when |
|---|---|---|
BankDetailsRequiredException |
Raised when attempting to create a payment for an employee without bank details. | |
PayCodeAlreadyExistsException |
A pay code with this code already exists | Raised when creating a custom pay code whose code collides with a system code or another of the employer's own codes (the two share a lookup namespace). |
PayCodeNotDeletableException |
Pay code cannot be deleted | Raised when attempting to delete a system/control/employer pay code or one that is in use. |
PayCodeNotEditableException |
Pay code cannot be edited | Raised when attempting to edit a system pay code or a pay code that is in use. |
PayLineHoursNotAllowedException |
Hours can only be set on the basic pay line of a regular hourly-paid employee | Raised when setting period hours on a payline that doesn't support it (not the basic pay line, or an employee who isn't a regular hourly-paid worker). |
PaymentAlreadyExistsException |
This payrun already has a payment | Raised when a payment already exists for the payrun. The create serializer rejects this up-front; this covers two concurrent creates racing past that check onto the unique constraint. |
PaymentAlreadySubmittedException |
Payment has already been submitted | Raised when attempting to submit a payment that has already been submitted. |
PaymentNotDeletableException |
Payment cannot be deleted due do its status | Raised when attempting to modify a payment that is not in PENDING status. |
PaymentNotEditableException |
Payment cannot be modified when not in PENDING status | Raised when attempting to modify a payment that is not in PENDING status. |
PaymentNotFoundException |
Payment not found | Raised when a referenced payment batch does not exist for the employer. |
PaymentNotResetableException |
Payment cannot be reset | |
PaymentProcessorNotAvailableException |
Payment processor not available | Raised when no payment processor is available for the requested processor type. |
PaymentSubmissionFailedException |
Payment submission failed | Raised when submitting a payment batch to the processor fails. |
PayrunAlreadyStartedException |
A payrun already started for this tax year | Raised when attempting to start a payrun but one already exists for the tax year. |
PayrunInProgressException |
The current payrun for this pay schedule has not been finalized yet | Raised when attempting an operation that requires a finalized payrun but current one is not finalized. |
PayrunNotDeletableException |
Payrun cannot be deleted | Raised when attempting to delete a payrun that is not the current payrun. |
PayrunNotEditableException |
Payrun cannot be modified | Raised when attempting to modify a finalized payrun. |
PayrunNotFinalizableException |
Payrun cannot be finalized | Raised when attempting to finalize a payrun that is not in finalizable state. |
PayrunNotReopenableException |
Payrun cannot be reopened | Raised when attempting to reopen a payrun that cannot be reopened (not last payrun or not finalized). |
Pensions
| Code | Default message | Raised when |
|---|---|---|
AssessmentExistsException |
This employee has already been assessed for auto-enrolment | Exception raised when attempting to perform an assessment on an employee who has already been assessed. |
AssessmentNotPostponedException |
This employee's assessment has not been postponed | Exception raised when attempting to perform operations that require a postponed assessment, but the assessment has not been postponed. |
AutoEnrolmentBeforeStagingDateException |
Auto-enrolment cannot be dated before the employer's staging date | Exception raised when an auto-enrolment is dated before the employer's staging date. The employer has no auto-enrolment duties until its staging date, so nothing can be auto-enroled before it. Voluntary (non auto-enrolment) joiners are not bound by it. |
AutoEnrolmentExistsException |
This employee is already auto-enroled | Exception raised when attempting to auto-enrol an employee who is already auto-enrolled. |
ConnectedPensionProviderNotFoundException |
No connected integration was found for this pension provider | Exception raised when no connected external integration exists for the requested pension provider, so it cannot be synchronized or connected. |
DuplicateWorkerGroupEnrolmentException |
Employee is already enroled in this worker group | Exception raised when attempting to enrol an employee in a worker group they are already enrolled in. |
EmployeeExemptedFromAutoEnrolmentException |
This employee is currently exempted from auto-enrolment | Exception raised when attempting to perform auto-enrolment operations on an employee who is exempted from auto-enrolment. |
EmployeeNotAssessedException |
This employee has not been assessed for auto-enrolment yet | Exception raised when attempting to enrol an employee who has not been assessed for auto-enrolment eligibility. |
EnrolmentNotOptedOutException |
This enrolment is not opted out | Exception raised when a refund is attempted on an enrolment that has not been opted out. |
EnrolmentNotRefundableException |
Only auto-enrolments can be refunded | Exception raised when a refund is attempted on an enrolment that is not an auto-enrolment. Only auto-enrolment contributions can be refunded. |
ExternalOptOutsNotSupportedException |
This pension provider does not publish opt-outs made directly with it | Exception raised when opt-outs are pulled from a pension provider that does not publish the ones members made directly with it. |
InactiveEnrolmentException |
This pension enrolment is inactive | Exception raised when attempting to perform operations on an inactive enrolment. Enrolments that have been left/opted out cannot be modified. |
PensionProviderNotDeletableException |
Pension provider is in use and cannot be deleted | Exception raised when attempting to delete a pension provider that is in use. Pension providers with active schemes/enrolments cannot be deleted. |
PensionProviderNotEditableException |
Pension provider is in use and cannot be modified | Exception raised when attempting to edit a pension provider that is in use. Pension providers with active schemes/enrolments cannot be modified. |
PensionSchemeConfigurationException |
Exception raised when pension scheme configuration is invalid. Used for validation errors such as missing required fields or incompatible settings. | |
PensionSchemeNotDeletableException |
Pension scheme is in use and cannot be deleted | Exception raised when attempting to delete a pension scheme that is in use. Pension schemes with active enrolments cannot be deleted. |
PensionSchemeNotEditableException |
Pension scheme is in use and cannot be modified | Exception raised when attempting to edit a pension scheme that is in use. Pension schemes with active enrolments cannot be modified. |
PensionSchemeNotQualifying |
Pension scheme is not qualifying for auto-enrolment | Exception raised when attempting to use a non-qualifying pension scheme for auto-enrolment purposes. Only qualifying schemes can be used for automatic enrolment. |
PostponementMaxLimitReachedException |
Auto-enrolment assessment cannot be postponed for more than 3 months after start date | Exception raised when attempting to postpone an assessment beyond the 3-month maximum limit from employment start date. |
SubmissionNotDeletableException |
This submission can no longer be deleted | Exception raised when deleting a contributions submission that is in-flight at the provider (SENT, with a poll queued against it) or already accepted (SUCCESS). |
SubmissionNotPollableException |
Polling is only available for submissions that have been sent or failed | Exception raised when polling is requested for a submission that has not been sent or failed, so there is no external status to check. |
SubmissionPayrunNotResolvableException |
No single finalized payrun matches this submission's period | Exception raised when a contributions submission cannot be tied to exactly one finalized payrun for its period (none found, or several across schedules match). |
WorkerGroupNotDeletableException |
Worker group is in use and cannot be deleted | Exception raised when attempting to delete a worker group that is in use. Worker groups with active enrolments cannot be deleted. |
WorkerGroupNotEditableException |
Worker group is in use and cannot be modified | Exception raised when attempting to edit a worker group that is in use. Worker groups with active enrolments cannot be modified. |
WorkerGroupRequiredException |
NEST requires a worker group to be specified | Exception raised when a NEST contributions submission is built without the worker groups NEST requires. |
RTI
| Code | Default message | Raised when |
|---|---|---|
RTICredentialsCheckException |
Could not verify your RTI credentials with HMRC. | Exception raised when the RTI credentials check could not be completed (e.g. HMRC gateway unreachable or an unreadable response), as opposed to the credentials simply being rejected. |
RTICredentialsException |
Your RTI credentials were rejected by HMRC. | Exception raised when the RTI credentials were checked successfully but HMRC rejected them as invalid (wrong Government Gateway user id / password). |
RTICredentialsRequiredException |
RTI Credentials are required to perform this action. | Exception raised when RTI credentials are required but not available. |
RTIDocumentSignatureException |
Could not generate the document's IRmark signature. | Raised when the IRmark (the document's integrity signature) cannot be generated. Submitting an unsigned document guarantees an HMRC rejection, so the failure must surface rather than silently produce unsigned XML. |
RTISubmissionNotDeletable |
This submission can no longer be deleted. | Raised when deleting a submission HMRC has already accepted (SUCCESS). |
RTISubmissionNotEditable |
This submission can no longer be edited. | Raised when editing a submission that is no longer editable (SENT/SUCCESS). |
RTISubmissionNotSubmittable |
This submission cannot be submitted. | Raised when submitting a submission that cannot be sent (already SENT/SUCCESS, or XML not built). |
Statutory documents
| Code | Default message | Raised when |
|---|---|---|
InvalidTaxPeriodException |
Invalid tax period | Exception raised when a tax period number is invalid (not between 1 and 12). |
NoEmployeeDataInTaxYearException |
There is no data for this employee in tax year | Exception raised when attempting to generate a document for an employee who has no data in the specified tax year. |
Webhooks
| Code | Default message | Raised when |
|---|---|---|
WebhookURLAlreadyExistsException |
A webhook with this URL already exists for this employer. | Raised when creating or updating a webhook to a URL that already exists for the employer. |
WebhookURLNotAllowedException |
This webhook URL is not allowed. | Raised when a webhook URL targets a non-public address (SSRF guard). Covers a disallowed scheme, an unresolvable host, or a host that resolves to a loopback/link-local/private/reserved address: e.g. the cloud metadata endpoint or an internal service. |
Working patterns
| Code | Default message | Raised when |
|---|---|---|
InvalidScheduleException |
The provided schedule is invalid | Exception raised when a working pattern schedule is invalid. Used when schedule data doesn't match expected structure or validation fails. |
WorkingPatternEmployerMismatchException |
Working pattern employer should not change | Exception raised when a substitute working pattern belongs to a different employer. |
WorkingPatternNotDeletableException |
This working pattern is in use and cannot be deleted | Exception raised when attempting to delete a working pattern that is in use or is the default pattern. |
WorkingPatternNotEditableException |
This working pattern cannot be modified | Exception raised when attempting to edit a working pattern that cannot be modified. |
WorkingPatternNotWeekBasedException |
This working pattern does not use week days | Exception raised when a week-day operation is attempted on a looping (non week-day) working pattern. |