# 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:
There are four different API error types:
| Error Type | Description |
`RECORD_NOT_FOUND` | A requested record could not be found. |
`INVALID_REQUEST_PARAMETERS` | A request was invalid. |
`UNAUTHORIZED_REQUEST` | A request was unauthorized. |
`UNKNOWN_ERROR` | An 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 Type | Description |
`networkError` | The user's device is offline. |
`clientError` | There is a problem with the client integration. |
`systemError` | Pinwheel internal server error. |
`userActionRequired` | User action is required. |
`platformError` | Payroll platform error. |
`invalidAccountsConfiguration` | Invalid user account configuration. |
`invalidUserInput` | User error. |
`invalidLinkToken` | The Link token is invalid. |
Specific error codes include:
| type | code | description | message |
`networkError` | `networkError` | Thrown when the user's device is offline. | Uh oh, looks like your device is offline. Please try again later. |
`clientError` | `clientError` | This error is thrown when the client modal is in an erroneous state | Uh oh, looks like we're having trouble getting you connected. Please try again later. |
`clientError` | `connectionRateLimited` | This error is thrown when a client is rate limited | Uh oh, looks like we're having trouble getting you connected. Please try again later. |
`systemError` | `systemError` | This error is thrown when an internal server error occurs | Uh oh, looks like we're having trouble getting you connected. Please try again later. |
`userActionRequired` | `accountLocked` | This error is thrown when the user's account is locked. They will need to reach out to their account administrator to proceed. | Uh oh, looks like your account has been locked. Please contact your payroll administrator to proceed. |
`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` | `accountNotActive` | This error is thrown when a user attempts to login to an inactive account | Uh oh, your account is inactive. Please contact your payroll administrator to continue. |
`userActionRequired` | `accountLoggedIn` | This error is thrown when the user is already logged in via another method | Uh oh, looks like you're logged in already. Please log out of your account before trying again. |
`userActionRequired` | `mfaSetupRequired` | This error is thrown if MFA needs to be set up | 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` | `contactHelpDesk` | This error is thrown if the user needs to contact the help desk before proceeding | Uh oh, looks like your account has been locked. Please contact your payroll Help Desk to continue. |
`userActionRequired` | `directDepositDisabled` | This error is thrown if the account does not support any updates to direct deposit settings | Uh oh, your account does not support this action. Please contact your payroll administrator to continue. |
`userActionRequired` | `directDepositAllocationsDisabled` | This error is thrown if the account does not support partial direct deposit allotments | Uh oh, your account does not support this action. Please contact your payroll administrator to continue. |
`userActionRequired` | `sessionTimeout` | This 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. |
`platformError` | `dataNotAvailable` | This error occurs only for _Income and Employment_ jobs. It occurs when the user's payroll platform does not surface the data requested. | 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 and Geos. | Uh oh, looks like your account cannot be accessed from your location. |
`platformError` | `platformError` | This error is thrown when there is an issue with the platform integration. This can be due to API or UI updates, and will require changes to the integration | 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, eg. under 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 | Uh oh, something unexpected happened. We are trying to fix this as quickly as possible, so please try again later. |
`platformError` | `maxFailedAttempts` | This error is thrown if the user reaches the maximum number of login attempts | Uh oh, you've reached the maximum number of attempts. Please wait until your account is unlocked before trying again. |
`invalidAccountsConfiguration` | `invalidExistingSplit` | This 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 | Uh oh, your account does not support this action. Please contact your payroll administrator to continue. |
`invalidAccountsConfiguration` | `changesTemporarilyDisabled` | This error is thrown when a change is rejected due to existing changes that are still pending on the account | 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 accounts, 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. |
`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` | `invalidCredentials` | The user has entered invalid credentials | Uh oh, the credentials you entered are 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` | `challengeAnswerIncorrect` | The answer provided for the challenge question was invalid | Uh oh, the verification answer you provided is invalid. Please try again. |
`invalidUserInput` | `validationFailed` | This 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. |
`invalidUserInput` | `emailNotRegistered` | This error is thrown when the email provided has not been registered | 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` | `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` | `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` | `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. |
`invalidLinkToken` | `usedLinkToken` | The Link token has already been used | Uh oh, something unexpected happened. We are trying to fix this as quickly as possible, so please try again later. |
`invalidLinkToken` | `invalidLinkTokenSignature` | The Link token signature is invalid | Uh oh, something unexpected happened. We are trying to fix this as quickly as possible, so please try again later. |
`invalidLinkToken` | `invalidLinkToken` | The Link token is invalid | Uh oh, something unexpected happened. We are trying to fix this as quickly as possible, so please try again later. |
`invalidLinkToken` | `expiredLinkToken` | The Link token has expired | Uh 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](🔗).