Errors

Learn how error conditions are expressed in the Teller API

Teller uses standard HTTP response status codes to indicate the success or failure of a request. Status codes in the 2xx range denote a successful request. Status codes in the 4xx range denote a client error, e.g. not using a client certificate to make the request, a problem with the user access token, etc. Status codes in the 5xx range denote a problem on our end, e.g. a bank is unavailable and it's not possible or otherwise doesn't make sense to gracefully handle the exception.

Failed requests do not generate billing events

Status Codes

Here is a list of status codes currently in use by the Teller API

Name
200 OK
Type
Description
A successful request.
Name
400 Bad Request
Type
Description
The request was unacceptable. Used when a request that requires a client certificate is made without one.
Name
401 Unauthorized
Type
Description
A request was made without an access token where one was required.
Name
403 Forbidden
Type
Description
A request was made with an invalid or revoked access token.
Name
404 Not Found
Type
Description
The requested resource was not found.
Name
410 Gone
Type
Description
Indicates that the resource requested is no longer available and that condition is permanent, e.g. because a financial account was closed.
Name
422 Unprocessable Entity
Type
Description
A request was made with an invalid request body.
Name
502 Bad Gateway
Type
Description
A 500 level response was received when making a request to a financial institution where a graceful fallback is not possible, e.g. a payment instruction.

The Error Object

Detailed information about the error condition is returned in the response body as a JSON object.

An example error object

{
  "error": {
      "code": "bad_request",
      "message": "Missing certificate: Retry request using your Teller client certificate."
  }
}

Name
error
Type
object
Description
An object describing the error condition.
- Name
  code
  Type
  string
  Description
  The error condition.
- Name
  message
  Type
  string
  Description
  A human readable string describing the error and how to resolve it.

Enrollment Errors

From time to time enrollments can enter an unhealthy state, meaning Teller is unable to use it until the end-user takes the required action. When your application makes a request involving a disconnected enrollment Teller returns a 404 status code with an error code beginning with enrollment.disconnected.

To restore an unhealthy enrollment initialize Teller Connect in update mode and direct the user to reconnect.

When an enrollment enters a disconnected state, Teller can send a webhook event of type enrollment.disconnected.

Example enrollment disconnected error

{
  "error": {
    "code": "enrollment.disconnected.user_action.mfa_required",
    "message": "User MFA is required."
  }
}

Enrollment Error Codes

Name
enrollment.disconnected
Type
Description
A generic error used for when no more information is available.
Name
enrollment.disconnected.account_locked
Type
Description
Access to the account has been restricted by the financial institution.
Name
enrollment.disconnected.credentials_invalid
Type
Description
The end-user changed their authentication credentials to access the financial institution.
Name
enrollment.disconnected.enrollment_inactive
Type
Description
The enrollment has become disconnected due to inactivity.
Name
enrollment.disconnected.user_action.captcha_required
Type
Description
The end-user is required to solve a CAPTCHA.
Name
enrollment.disconnected.user_action.contact_information_required
Type
Description
The end-user is required to update their contact information.
Name
enrollment.disconnected.user_action.insufficient_permissions
Type
Description
The end-user does not have the required permissions to perform the requested operation.
Name
enrollment.disconnected.user_action.mfa_required
Type
Description
The end-user is required to complete a MFA challenge.
Name
enrollment.disconnected.user_action.web_login_required
Type
Description
The end-user is required to login to the financial institution's web online-banking, e.g. to accept FI terms and conditions.