Home Payroll API Payroll API error codes: Accounting to Pay schedule

Payroll API error codes: Accounting to Pay schedule

Last updated on Sep 19, 2026

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 1 of 2 of the list, generated from the API reference, version 0.5.0. It covers: Accounting, Benefits, CIS, Core, Employee, Employer, General, Integrations, Irregular workers, Leave, Opening balances, Pay schedule.

Accounting

Code Default message Raised when
MissingCodeMappingException Exception raised when pay codes are not mapped to nominal codes for an external accounting provider.
PayrunJournalNotBalancedException Exception raised when a payrun journal's debits don't equal credits. Accounting journals must balance (total debits = total credits).
PayrunJournalNotDeletableException Exception raised when attempting to delete a payrun journal that cannot be deleted.

Benefits

Code Default message Raised when
BenefitConfigurationException Benefit configuration error Exception raised when benefit configuration is invalid. Used for validation errors such as missing required fields, invalid benefit types, or incompatible settings.
BenefitNotDeletableException Benefit is in use and cannot be deleted Exception raised when attempting to delete a benefit that is in use. Benefits that have been included in finalized payruns or P11D forms cannot be deleted.
CompanyAssetNotDeletableException This company asset is linked to a benefit and cannot be deleted Raised when deleting a company car or van asset that is still linked to a benefit.

CIS

Code Default message Raised when
CISExcludedException This feature is not available to CIS subcontractors Exception raised when attempting to use a feature that is not available to CIS subcontractors. CIS subcontractors have restrictions on certain features (e.g., benefits).
CISOnlyException This feature is exclusive to CIS subcontractors Exception raised when attempting to use a feature that is exclusive to CIS subcontractors. Some features are only available to CIS subcontractors (e.g., CIS statements).
IrregularsOnlyException This feature is exclusive to irregulars Exception raised when attempting to use a feature that is exclusive to irregular workers. Some features are only available to irregular workers (e.g., irregular work assignments).

Core

Code Default message Raised when
AddressNotDeletableException This address is not deletable Exception raised when attempting to delete a default address. Default addresses cannot be deleted to ensure entities always have at least one address.
UnsupportedPayPeriodException This pay period has no corresponding pay frequency Exception raised when a PayPeriod has no corresponding PayFrequency code. Daily (and any future period without an RTI frequency mapping) cannot be converted for FPS/PAPDIS output.

Employee

Code Default message Raised when
EmployeeHasLeftException This employee has left Exception raised when attempting to perform an operation on an employee who has already left the company.
EmployeeHasNotStartedException This employee has not started yet Exception raised when attempting to perform an operation on an employee who has not yet started their employment.
EmployeeHoldException Exception raised when attempting to place an employee on hold or release from hold when the operation is not valid (e.g., already on hold, not on hold).
EmployeeInactiveException This employee is inactive Exception raised when attempting to perform an operation on an inactive (former) employee.
EmployeeNotDeletableException This employee cannot be deleted Exception raised when attempting to delete an employee that cannot be deleted (e.g., has finalized payslips).
MinimumWageNotMetException Exception raised when an employee's pay does not meet the minimum wage requirements.
NILetterException Exception raised when there is an issue with National Insurance letter processing.
NINORequiredException Employee's NINO is not defined Exception raised when an operation requires the employee's National Insurance number but it is not defined (e.g. verifying the NINO with HMRC).
OffPayrollWorkersExcludedException This feature is not available to off-payroll workers Exception raised when attempting to use a feature that is not available to off-payroll workers.
TaxCodeException A Tax code error occurred Exception raised when there is an error with tax code validation or processing.

Employer

Code Default message Raised when
ApprenticeLevyNotEnabledException Apprenticeship Levy is not enabled for this employer Exception raised when attempting to use apprenticeship levy features when apprenticeship levy is not enabled for the employer.
EmploymentAllowanceMaxClaimExceededException Employment Allowance amount exceeds the HMRC annual maximum Exception raised when the requested Employment Allowance amount exceeds the HMRC annual maximum for the tax year.
InvalidTaxYearDataException Invalid or incomplete tax year data Exception raised when a tax year directory cannot be loaded (missing or incomplete base.json, or no 'tax_year' key). Fatal on purpose: bad tax-year data must stop startup rather than silently drop a year from available_tax_years.
TaxYearNotAvailableException This tax year is not available for the employer Exception raised when attempting to access a tax year that is not available for the employer.
TaxYearNotEditableException This tax year is not editable Exception raised when attempting to edit data for a tax year that is not editable (e.g., not the current tax year).
YearEndReachedException This tax year has ended Exception raised when attempting to perform operations after the tax year has ended.

General

Code Default message Raised when
AccountActivationException Account activation failed Raised when an account activation link is malformed or does not match a user
AdminPermissionRequiredException Raised when a non-admin user tries to perform an admin-only action
BureauOnlyException
CannotDeleteLastAdminException Raised when trying to delete the last admin user
CannotDowngradeLastAdminException Raised when trying to downgrade the last admin user
CaptchaVerificationException Captcha verification failed Raised when the Cloudflare Turnstile token sent with an anonymous request is missing, invalid, expired, already used, or could not be checked.
CustomNotAuthenticated
DuplicateMemberException Raised when trying to create an access level for an email that already has access
EmailAlreadyInvitedException Raised when trying to invite an email that already has a pending invitation
EmployerQuotaExceededException
FeatureNotAvailableException This feature is not currently available Raised when a feature is not currently available (e.g. not yet implemented or disabled), so the caller gets a clear message instead of an unhandled error. Wrap in BadRequest.
InactiveMembershipSubscriptionException The subscription is not active. Raised when an operation requires an active subscription but it isn't active (e.g. cancelling an already-inactive one). A trivial user/state error, not a payment-platform failure: surfaced as a 400, not worth logging.
MalformedURLException The request URL is malformed. Raised when a view is reached without a URL kwarg its route is supposed to supply (e.g. employer_pk, tax_year). This is a routing/configuration error, never a client mistake: hence a 500: but it still returns the structured error envelope.
MembershipRequiredException
OnboardingAlreadyCompletedException Onboarding has already been completed for this account Raised when onboarding is re-submitted for a customer entity that has already completed it. Onboarding creates an Employer (with ownership) or a Bureau, so replays must be rejected rather than minting duplicates. Wrap in BadRequest.
PaymentPlatformException The payment platform could not complete the request. Please try again later. Raised when a call to the payment platform (Stripe) fails, so the error is surfaced to the user instead of leaking as a 500.
PaymentRequiredException
SocialAccountConflictException This email is already registered with a different sign-in method Raised when a social login resolves an email that already belongs to a local (password) account or an account linked to a different provider. Social and local identities never merge, so we refuse rather than link.
TokenAuthRequiredException This endpoint requires a user access token. API key credentials are not accepted here. Raised when a request carrying API key credentials reaches an endpoint that acts on behalf of a signed-in person: account settings, team membership, billing. The credentials are valid; they are simply the wrong kind for this route, which is why this is a 403 and not a 401. A 401 would invite the client to refresh and retry forever.
UserAlreadyExistsException An account already exists for this email address Raised when an account is requested for an email that already has one.

Integrations

Code Default message Raised when
CSVParsingException Unable to parse the CSV file Raised when an imported CSV file cannot be parsed (malformed rows, bad column mapping, empty file).
CompanyNotFoundException Company not found on provider Raised when a tenant/company lookup on the provider returns a non-success response (e.g. wrong tenant_id).
ContributionsAlreadyQueuedException A contributions file for this scheme is still being processed by the provider Raised when a contributions file for the same scheme is still in flight. The People's Pension accepts one file per account at a time and rejects the next one with "A file is already queued for processing" until the previous file reaches the processed state.
ExternalProviderNotConnectedException Raised when the provider is not connected or credentials have expired.
ExternalProviderOperationException Raised when an API operation fails. Includes HTTP status and response body.
IntegrationProviderException Base exception for integration-related errors.
MissingContributionDataException Missing data required by the pension provider Raised when an employee in a contributions submission is missing data the provider requires.
PayReferencePeriodMismatchException The submitted period does not match the provider's next pay reference period Raised when a contributions period does not match the one the provider expects next. The People's Pension validates the submitted payReferencePeriod against the nextPayReferencePeriod it advertises on the account, and rejects the file when they differ. Failing here surfaces an actionable message instead of a provider validation failure hours later.

Irregular workers

Code Default message Raised when
AssignmentOverlapException Some assignments are overlapping Exception raised when assignments overlap with each other.
AssignmentOverlapsLeaveException Assignment cannot overlap with an existing leave Exception raised when an assignment overlaps with an existing leave period.
IrregularWorkAssignmentInvalidDatesException Assignment end date must be after start date Exception raised when assignment dates are invalid (e.g., end before start, outside boundaries).
IrregularWorkAssignmentNotDeletableException Irregular work assignment cannot be deleted Exception raised when attempting to delete an assignment in a closed pay period.
IrregularWorkerRateDuplicateNameException A rate with this name already exists for this employee Exception raised when attempting to create a rate with a name that already exists for the employee.
IrregularWorkerRateNotDeletableException Cannot delete default rate Exception raised when attempting to delete a default rate.
PayPeriodClosedException A pay period is closed Exception raised when attempting to modify assignments in a closed pay period.

Leave

Code Default message Raised when
EmployeeNotLeaverException Employee is not leaver Raised when an operation requires an employee to be a leaver but they are not.
EntitlementBasisNotEditableException Holiday entitlement basis cannot be changed when employee has leave history or remnant allowance from previous years Raised when attempting to change holiday entitlement basis for employee with leave history or remnant allowance.
InvalidHolidayEntitlementBasisException Irregular workers must use HOURS_PER_WEEK as holiday entitlement basis Raised when irregular employee uses incorrect holiday entitlement basis (must be HOURS_PER_WEEK).
InvalidLeaveDatesException An error occurred Raised when leave dates are invalid (e.g., leave_to <= leave_from, before start date, after leave date).
InvalidLeaveFieldException An error occurred Raised when a leave field is missing or incompatible with the leave type (partial-day times, baby date, neonatal care payment tier / start / end dates).
InvalidLeavePayException An error occurred Raised when leave pay type is incompatible with leave type (e.g., DO_NOT_PAY for holiday, STATUTORY_PAY for unauthorized).
InvalidResignationDateException Raised when resignation date is invalid (e.g., before last finalized payslip end date).
LeaveAllowanceExceededException An error occurred Raised when attempting to use more leave allowance than available.
LeaveNotDeletableException An error occurred Raised when attempting to delete a leave that overlaps with finalized payruns.
LeaveNotEditableException An error occurred Raised when attempting to edit a leave that overlaps with finalized payruns.
LeaveOverlapException An error occurred Raised when a leave overlaps with another existing leave for the same employee.
LeavePreviewNotAvailableException Leave preview is not available: the employee has no working pattern Raised when a leave preview cannot be computed (e.g. the employee has no working pattern).
OverrideHoursTotalException Holiday pay for casual workers require total hours information Raised when override_hours_total is missing or incorrectly set for irregular employees.
SSPWeekBreakdownException SSP week breakdown is required and must match the number of administrative weeks in the leave period Raised when SSP week breakdown is missing or has incorrect length for irregular employees.
StatutoryPayRequirementException An error occurred Raised when statutory pay requirements are not met (e.g., insufficient earnings, employment duration, etc.).

Opening balances

Code Default message Raised when
DuplicateNILetterException A NIC summary for this NI letter already exists in this tax year Raised when a NIC summary would violate the unique (employee, ni_letter, tax_year) constraint.
OpeningBalancesNotAvailableForTaxYearException An error occurred Exception raised when opening balances cannot be set for a tax year. Typically occurs when employee's start date is on or before the tax year start date, meaning there are no previous periods to carry forward balances from.

Pay schedule

Code Default message Raised when
PayScheduleConfigurationException Exception raised when pay schedule configuration is invalid. Used for validation errors such as mismatched tax years, invalid dates, or invalid day numbers for monthly schedules.
PayScheduleNotDeletableException A payrun already started for this tax year Exception raised when attempting to delete a pay schedule that has payruns or is the only default schedule for a period.
PayScheduleNotEditableException A payrun already started for this tax year Exception raised when attempting to edit a pay schedule that has payruns. Once payruns exist, certain fields (dates, period, tax_year) cannot be changed.