GuidesAPI ReferenceChangelog
Log In
Guides

Link Errors

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.

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.

Error Types

Error types are the broad category of the error. All of these errors are terminal, meaning users cannot proceed past this point. You should handle the error on your side by either creating a new link token and trying again or sending users to an alternative flow. 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.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 stateLooks like we're having trouble getting you connected. Please try again later.
clientErrorconnectionRateLimitedThis error is thrown when a client is rate-limited.Looks like we're having trouble getting you connected. Please try again later.

invalidLinkToken codes

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