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.

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.

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.