API Errors

Pinwheel API error messages are returned in JSON format inside an error object. The type field contains a higher level category of the error and the code field is more specific. The message field contains a human-readable description of the error and is subject to change. For example, an error response to POST /link_tokens could look like:

{
  "error": {
    "type": "INVALID_REQUEST_PARAMETERS",
    "code": "INVALID_ROUTING_NUMBER",
    "message": "Validation error.",
    "status_code": 400,
    "fields": [{
      "message": "Provided value doesn't match valid format.",
      "name": "routing_number"
    }]
  }
}

There are four different API error types:

Error TypeDescription
RECORD_NOT_FOUNDA requested record could not be found.
INVALID_REQUEST_PARAMETERSA request was invalid.
UNAUTHORIZED_REQUESTA request was unauthorized.
UNKNOWN_ERRORAn unknown error occurred.

The optional fields attribute holds an array of validation errors. It is human-facing and shouldn't be programatically processed since its structure and content may change arbitrarily. Use type and code as stable fields for programmatic handling.

Link Errors

An onError event will fire for every error. Errors may be retryable (e.g., an incorrect credential was entered) or may be terminal (e.g., the 3rd party integration is currently down). If an error occurred before closing the modal, Link's onExit callback is called with an error object as well.

Link error codes and types are safe for developer use, whereas error messages are liable to change.

There are eight different Link error types:

Error TypeDescription
networkErrorThe user's device is offline.
clientErrorThere is a problem with the client integration.
systemErrorPinwheel internal server error.
userActionRequiredUser action is required.
platformErrorPayroll platform error.
invalidAccountsConfigurationInvalid user account configuration.
invalidUserInputUser error.
invalidLinkTokenThe Link token is invalid.

Specific error codes include:

typecodedescriptionmessage
networkErrornetworkErrorThrown when the user's device is offline, or when there is an issue communicating with the server.Uh oh, looks like your device is offline. Please try again later.
clientErrorclientErrorThis error is thrown when the client modal is in an erroneous stateUh oh, looks like we're having trouble getting you connected. Please try again later.
clientErrorconnectionRateLimitedThis error is thrown when a client is rate limitedUh oh, looks like we're having trouble getting you connected. Please try again later.
systemErrorsystemErrorAn unhandled error when a payroll integration behaves in an unexpected manner. These errors are fixed such that subsequent users do not trigger themUh oh, looks like we're having trouble getting you connected. Please try again later.
userActionRequiredaccountLockedThis 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.
userActionRequiredchangePasswordRequiredThis error indicates that the user must update their password before logging inUh oh, you will need to update your password before proceeding. Please login through your payroll provider to continue.
userActionRequiredaccountNotActiveThis error is thrown when a user attempts to login to an inactive account, eg. if they've been terminated and have lost accessUh oh, your account is inactive. Please contact your payroll administrator to continue.
userActionRequiredaccountLoggedInThis error is thrown if the platform detects that the user is logged in via another mechanismUh oh, looks like you're logged in already. Please log out of your account before trying again.
userActionRequiredmfaSetupRequiredThis error is thrown if MFA needs to be set up, eg. on first time loginUh oh, you'll need to set up multi-factor authentication before proceeding. Please login through your payroll provider to complete setup before trying again.
userActionRequiredcontactHelpDeskThis error is thrown if the user needs to contact their payroll admin in order to continue.Uh oh, looks like your account has been locked. Please contact your payroll Help Desk to continue.
userActionRequireddirectDepositDisabledThis error is thrown if the account does not support any updates to direct deposit settings, eg. the employer has disabled the ability to update settings within the online portalUh oh, your account does not support this action. Please contact your payroll administrator to continue.
userActionRequireddirectDepositAllocationsDisabledThis error is thrown if the account does not support direct deposit switches through the online portal, similar to directDepositDisabledUh oh, your account does not support this action. Please contact your payroll administrator to continue.
userActionRequiredsessionTimeoutThis error occurs when the session closes after a period of inactivity, eg. due to lack of user action.Uh oh, looks like your session has timed out. Please exit and try again.
platformErrordataNotAvailableThis error occurs only for Income and Employment jobs. It occurs when the user's payroll platform does not surface the data requested. The availability of data varies within platform, employer, and employee combinations.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.
platformErrorlocationRestrictedThis error is thrown if the platform cannot be accessed at the user's current location. Eg, 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.
platformErrorplatformErrorThis error is thrown when there is an issue with the underlying payroll platform. While our connection is behaving as expected, the platform itself is not working as expected.Uh oh, looks like we’re having trouble getting you connected. Please try again later.
platformErrorplatformUnavailableThis error is thrown when the platform is unavailable, eg. some platforms will go offline during routine maintenanceUh oh, looks like we're having trouble getting you connected. Please try again later.
platformErrorroutingNumberRejectedThis error is thrown when the routing number provided in the Link token is rejected by the platform's validation logicUh oh, something unexpected happened. We are trying to fix this as quickly as possible, so please try again later.
platformErrormaxFailedAttemptsThis error is thrown if the user reaches the maximum number of login attemptsUh oh, you've reached the maximum number of attempts. Please wait until your account is unlocked before trying again.
invalidAccountsConfigurationinvalidExistingSplitThis error is thrown when the user's account does not support the requested change, eg. a user attempts to add a fixed amount allocation to an account that has an existing percentage allocation. Validation rules vary from platform to platformUh oh, your account does not support this action. Please contact your payroll administrator to continue.
invalidAccountsConfigurationchangesTemporarilyDisabledThis error is thrown when a change is rejected due to existing changes that are still pending on the account, eg. a direct deposit switch has been submitted and is pending processingUh oh, looks like your account has pending changes. Please wait for them to complete before trying again.
invalidAccountsConfigurationmaxAccountsThis error is thrown when a user has reached the maximum number of direct deposit allocations, such that a new one cannot be addedUh oh, you've reached the maximum number of accounts. Please remove one via your payroll provider before trying again.
invalidUserInputmfaTimeExceededThis error is thrown when the MFA token expiresUh oh, the request has timed out. Please try again. Please try again.
invalidUserInputinvalidCredentialsThe user has entered invalid credentialsUh oh, the credentials you entered are invalid. Please try again.
invalidUserInputinvalidMfaCodeThe MFA code that was entered was invalidUh oh, the authentication code you entered is invalid. Please try again.
invalidUserInputchallengeAnswerIncorrectThe answer provided for the challenge question was invalid, eg. during an MFA stepUh oh, the verification answer you provided is invalid. Please try again.
invalidUserInputvalidationFailedThis is a catch-all error that is thrown to capture other validation issues (eg. driver's license)Uh oh, the information you entered is invalid. Please try again.
invalidUserInputemailNotRegisteredThis error is thrown when the email address provided by the user has not been registered with the payroll platformUh 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.
invalidUserInputpasswordsNotEqualThis error is thrown in the password reset flow, when a password and its confirmation do not matchUh oh, the passwords do not match. Please try again.
invalidUserInputinvalidInputThis is a catch-all error that is thrown to capture generic input errorsUh oh, the information you entered is invalid. Please try again.
invalidUserInputtimedOutWithNoInputThis 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.
invalidLinkTokenusedLinkTokenThe Link token has already been usedUh oh, something unexpected happened. We are trying to fix this as quickly as possible, so please try again later.
invalidLinkTokeninvalidLinkTokenSignatureThe Link token signature is invalidUh oh, something unexpected happened. We are trying to fix this as quickly as possible, so please try again later.
invalidLinkTokeninvalidLinkTokenThe Link token is invalidUh oh, something unexpected happened. We are trying to fix this as quickly as possible, so please try again later.
invalidLinkTokenexpiredLinkTokenThe Link token has expiredUh oh, something unexpected happened. We are trying to fix this as quickly as possible, so please try again later.

Please contact [email protected] for access to our Developer Dashboard.


Did this page help you?