Job Errors
Pinwheel runs a login job when a user connects an account. After the connection is established, Pinwheel executes jobs for performing a direct deposit switch or retrieving platform core data.
Looking for a different category of errors?
Pinwheel's system also communicates API Errors and Link SDK Errors.
Sometimes, these jobs fail. You can listen for failure by registering for webhook events or listening to the onError callback on the Link SDK. See Link SDK Errors for more information about this callback.
These error types and codes are enums that are safe for developer use, whereas error messages are liable to change. Pinwheel may introduce new error types and codes as non-breaking changes per the company's Change Management policy.
Error Types
There are five different error types:
| Error Type | Description |
|---|---|
invalidAccountsConfiguration | Invalid user account configuration. |
invalidUserInput | User error. |
platformError | Payroll platform error. |
systemError | Pinwheel internal server error. |
userActionRequired | User action is required. |
Error codes for invalidAccountsConfiguration error type
invalidAccountsConfiguration error type| Error Type | Error Code | Description | Message |
|---|---|---|---|
invalidAccountsConfiguration | changesTemporarilyDisabled | This error is thrown when a change is rejected due to existing changes that are still pending on the account, e.g., a direct deposit switch has been submitted and is pending processing. | Uh oh, looks like your account has pending changes. Please wait for them to complete before trying again. |
invalidAccountsConfiguration | maxAccounts | This error is thrown when a user has reached the maximum number of direct deposit allocations, such that a new one cannot be added. | Uh oh, you've reached the maximum number of accounts. Please remove one via your payroll provider before trying again. |
Error codes for invalidUserInput error type
invalidUserInput error type| Error Type | Error Code | Description | Message |
|---|---|---|---|
invalidUserInput | challengeAnswerIncorrect | The answer to the challenge question was invalid, e.g., during an MFA step. | Uh oh, the verification answer you provided is invalid. Please try again. |
invalidUserInput | emailNotRegistered | This error is thrown when the email address provided by the user has not been registered with the payroll platform. | Uh oh, the email you are trying to use has not been registered. Please try again with a different email or contact your payroll administrator for help. |
invalidUserInput | invalidCredentials | The user has entered invalid credentials. | Uh oh, the credentials you entered are invalid. Please try again. |
invalidUserInput | invalidInput | This is a catch-all error that is thrown to capture generic input errors | Uh oh, the information you entered is invalid. Please try again. |
invalidUserInput | invalidMfaCode | The MFA code that was entered was invalid | Uh oh, the authentication code you entered is invalid. Please try again. |
invalidUserInput | mfaTimeExceeded | This error is thrown when the MFA token expires | Uh oh, the request has timed out. Please try again. Please try again. |
invalidUserInput | passwordsNotEqual | This error is thrown in the password reset flow when a password and its confirmation do not match. | Uh oh, the passwords do not match. Please try again. |
invalidUserInput | timedOutWithNoInput | This error is thrown if the Link modal is left up for 15 minutes without user input submitted. | Uh oh, looks like your device has been disconnected. Please exit and try again. |
invalidUserInput | validationFailed | This is a catch-all error that is thrown to capture other validation issues (e.g. driver's license) | Uh oh, the information you entered is invalid. Please try again. |
Error codes for platformError error type
platformError error type| Error Type | Error Code | Description | Message |
|---|---|---|---|
platformError | cardNotSupported | This error is thrown if the account does not support updates with this card. | Uh oh, this card type is unsupported. Please contact your payroll administrator for assistance |
platformError | cardNumberRejected | This error is thrown if the card number is rejected by the account. | Uh oh, this card number was rejected. Please contact your payroll administrator for assistance. |
platformError | dataNotRefreshable | This error occurs only for Income and Employment jobs. It is raised when the user's payroll platform can surface the data requested when the user starts a new link session but not when the job is run via a refresh. Data availability sometimes requires user action, such as an MFA code input, to retrieve the requested data. | This error is applicable to any job that is part of the Income and Employment suite (Income, Employment, Identity, Paystubs, Shifts, and Direct Deposit Allocations). Since this error is only viewable asynchronously via the job results endpoint, there is no message shown to the user in the Link modal. |
platformError | locationRestricted | This error is thrown if the platform cannot be accessed at the user's current location. For example, some employers restrict access to corporate networks or from specific IPs or locations. | Uh oh, looks like your account cannot be accessed from your location. |
platformError | maxFailedAttempts | This error is thrown if the user reaches maximum login attempts. | Uh oh, you've reached the maximum number of attempts. Please wait until your account is unlocked before trying again. |
platformError | platformError | This error is thrown when there is an issue with the underlying payroll platform. While our connection behaves as expected, the platform is not working as expected. | Uh oh, looks like we’re having trouble getting you connected. Please try again later. |
platformError | platformUnavailable | This error is thrown when the platform is unavailable, e.g., some platforms will go offline during routine maintenance. | Uh oh, looks like we're having trouble getting you connected. Please try again later. |
platformError | routingNumberRejected | This error is thrown when the routing number provided in the Link token is rejected by the platform's validation logic. | Uh oh, something unexpected happened. We are trying to fix this as quickly as possible, so please try again later. |
Error codes for systemError error type
systemError error type| Error Type | Error Code | Description | Message |
|---|---|---|---|
systemError | systemError | An unhandled error occurs when a payroll integration behaves unexpectedly. These errors are fixed such that subsequent users do not trigger them | Uh oh, looks like we're having trouble getting you connected. Please try again later. |
Error codes for userActionRequired error type
userActionRequired error type| Error Type | Error Code | Description | Message | |
|---|---|---|---|---|
userActionRequired | accountLocked | This error is thrown when the user's account has been locked. Users will need to reach out to their HR Admin to proceed. | Uh oh, looks like your account has been locked. Please contact your payroll administrator to proceed. | |
userActionRequired | accountLoggedIn | This error is thrown if the platform detects that the user is logged in via another mechanism. | Uh oh, looks like you're logged in already. Please log out of your account before trying again. | |
userActionRequired | accountNotActive | This error is thrown when a user attempts to log in to an inactive account, e.g., if they've been terminated and have lost access. | Uh oh, your account is inactive. Please contact your payroll administrator to continue. | |
userActionRequired | cardSwitchDisabled | This error is thrown if the account does not support any updates to card settings, e.g., the employer has disabled the ability to update settings within the online portal. | Uh oh, your account does not support this action. Please contact your payroll administrator to continue. | |
userActionRequired | changePasswordRequired | This error indicates that the user must update their password before logging in. | Uh oh, you will need to update your password before proceeding. Please login through your payroll provider to continue. | |
userActionRequired | contactHelpDesk | This error is thrown if the user needs to contact their payroll admin to continue. | Uh oh, looks like your account has been locked. Please contact your payroll Help Desk to continue. | |
userActionRequired | directDepositAllocationsDisabled | This error is thrown if the account does not support direct deposit switches through the online portal, similar to directDepositDisabled | Uh oh, your account does not support this action. Please contact your payroll administrator to continue. | |
userActionRequired | directDepositDisabled | This error is thrown if the account does not support any updates to direct deposit settings, e.g., the employer has disabled the ability to update settings within the online portal. | Uh oh, your account does not support this action. Please contact your payroll administrator to continue. | |
userActionRequired | mfaSetupRequired | This error is thrown if MFA needs to be set up, e.g., on first-time login | Uh oh, you'll need to set up multi-factor authentication before proceeding. Please login through your payroll provider to complete setup before trying again. | |
userActionRequired | sessionTimeout | This error occurs when the session closes after a period of inactivity, e.g., due to a lack of user action. | Uh oh, looks like your session has timed out. Please exit and try again. | |
userActionRequired | payoutCardsDisabled | This error is thrown if the account does not support card switches through the online portal, similar to cardSwitchDisabled | Uh oh, your account does not support this action. Please contact your payroll administrator to continue. |
Updated 20 days ago