GuidesAPI ReferenceChangelog
Log In
Guides

Within Link there are two types of errors that may occur. Job Errors are errors that occur during the running of a job (e.g. login, direct deposit switch) on the backend. Link Errors are errors that occur prior to backend job initialization.

📘

Looking for a different category of errors?

Pinwheel's system also communicates API Errors.

Error Handling

Errors can be handled by your client code using one of three methods:

  1. The onError callback
  2. The onEvent callback with "error" event
  3. If an error has occurred before closing the modal, Link's onExit callback is called with an error object

Error event payloads have the format outlined below.

KeyTypeDescription
typestringError type is the broad category of error. Read more here.
codestringError code is the specific error code. Read more here.
messagestringThe error message shown to the end user.
pendingRetrybooleanSometimes jobs fail on the initial attempt. This field indicates if the job that has errored will be retried or not. Retries occur asynchronously and within 24 hours. The result of this retried job will be sent via a webhook.

🚧

Users may be able to proceed after error events

Errors surfaced via the error event do not necessarily mean the user can no longer continue to successfully complete the flow. For example, the error with code invalidCredentials fires when a user inputs invalid credentials, however, the user can proceed despite this error.

Error Types

Error types are the broad category of the error. There are three different types of link errors:

Error TypeDescription
networkErrorThe user's device is offline.
clientErrorThere is a problem with the SDK integration.
invalidLinkTokenThe Link token is invalid.

Error Codes

Error codes exist within error types. They are more specific indicators than the type.

networkError codes

typecodedescriptionmessage
networkErrornetworkErrorThrown when the user's device is offline, or there is an issue communicating with the server.Uh oh, looks like your device is offline. Please try again later.

clientError codes

typecodedescriptionmessage
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-limited.Uh oh, looks like we're having trouble getting you connected. Please try again later.

invalidLinkToken codes

typecodedescriptionmessage
invalidLinkTokenexpiredLinkTokenThe link token has expired.Uh oh, something unexpected happened. We are trying to fix this as quickly as possible, so please try again later.
invalidLinkTokeninvalidLinkTokenThe link token is invalid.Uh oh, something unexpected happened. We are trying to fix this as quickly as possible, so please try again later.
invalidLinkTokeninvalidLinkTokenSignatureThe 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.
invalidLinkTokenusedLinkTokenThe 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.

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