Errors

Common errors returned and their formats

The API returns JSON with an error code and description in case of any error during the request as shown. In case the error is in a specific field, it also returns the field name in an error object.

{
  "error": {
    "en": "Generic Error Description"
  },
  "error_code": "400",
  "http_code": "409",
  "success": false
}

Understanding Error Codes

Please remember to check the http_status, error_status, and JSON associated with the error response to better understand the error.

Error Messages

When building out your application, we recommend relying only on the HTTP Status and Error Codes for your error handling logic. Error messages are subject to change.

HTTP Status Codes

HTTP_CODE
Description

200 OK

Worked as expected

202 Accepted

Accepted, but not final response

400 Bad Request

Bad request to API. Missing a field or an invalid field.

401 Not Authorized

Authentication error

402 Request Failed

Request to the API failed

404 Not Found

Cannot be found

409 Conflict

Incorrect values supplied (eg. Insufficient balance, wrong MFA response, incorrect micro deposits, etc.)

429 Too Many Requests

Too many requests hit the API too quickly.

500 Server Error

Internal server error

503 Service Unavailable

Service unavailable. The server is currently unable to handle the request due to a temporary overload or scheduled maintenance.

504 Gateway Timeout

The server was acting as a gateway or proxy and did not receive a timely response from the upstream server.

Error Codes

ERROR_CODE
Description

0

Success

10

Accepted, but action pending

100

Incorrect client credentials

110

Incorrect user credentials

120

Unauthorized fingerprint

200

Error in payload (error in payload formatting)

300

Unauthorized action (User/Client not allowed to perform this action)

400

Incorrect values supplied (eg. Insufficient balance, wrong MFA response, incorrect micro deposits)

404

Object not found

410

Action not allowed on the object (either you do not have permission or the action on this object is not supported)

429

Too many requests hit the API too quickly.

450

Idempotency key already in use

460

Request failed but not due to server error

500

Server error

503

Service unavailable. The server is currently unable to handle the request due to a temporary overload or scheduled maintenance.

504

The server was acting as a gateway or proxy and did not receive a timely response from the upstream server.

Bank Login - Authentication Errors

HTTP_CODE
ERROR_CODE
Description

400

200

Triggered when something is not correct at the payload level. Mostly always for bad user credentials. But can also be triggered when payload is not formatted correctly or the institution is not supported.

402

460

No ACH capable account found

402

500

Either the account is locked or the bank is requesting user's attention (because they are not set up completely or set up or for some other reason).

503

503

Service unavailable due to Bank or Synapse maintenance.

Bank Login - Sync Errors

HTTP_CODE
ERROR_CODE
Description

503

503

Refresh temporarily unavailable: This account is eligible for refresh but a temporary error (e.g. bank maintenance) caused it to fail. Try again later.

400

410

Refresh not allowed: Refresh is not supported for the selected bank (e.g. Ally).

401

110

Bad credentials: Update the user's credentials by re-linking the account via bank logins.

500

500

Unknown refresh error: Not to be confused with a general server error or unknown login error.

Errors


Common errors returned and their formats

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.