Errors

Errors overview

We use standard HTTP response codes for success and failure notifications, and our errors are further classified by error_type. In general, 200 HTTP codes correspond to success, 40X codes are for developer- or user-related failures, and 50X codes are for Okra-related issues. We’re always working to minimize API errors related to Okra integrations and to address connectivity issues across bank infrastructure.

Error schema

{
"error_type": String,
"error_code": String,
"error_message": String,
"display_message": String
}

All errors returned by the API include the following data elements:

Field

Description

error_type String

A broad categorization of the error. One of: INVALID_REQUEST, INVALID_INPUT, BANK_ERROR, RATE_LIMIT_EXCEEDED, API_ERROR, or RECORD_ERROR. Safe for programmatic use.

error_code String

The particular error code. Each error_type has a specific set of error_codes. Safe for programmatic use.

error_message String

A developer-friendly representation of the error code. This may change over time and is not safe for programmatic use.

display_message String, nullable

A user-friendly representation of the error code. null if the error is not related to user action. This may change over time and is not safe for programmatic use.

Invalid request errors

Returned when the request is malformed and cannot be processed.

Invalid request errors

{
"error_type": "INVALID_REQUEST",
"http_code": Enum (400, 404),
"error_code": Enum (
"MISSING_FIELDS",
"UNKNOWN_FIELDS",
"INVALID_FIELD",
"INVALID_BODY",
"INVALID_HEADERS",
"NOT_FOUND",
"SANDBOX_ONLY"
)
"error_message": String
"display_message": Null,
"request_id": String
}

All errors returned by the API include the following data elements:

Error Code

Notes

MISSING_FIELDS HTTP 400

The request was missing one or more required fields. The error_message field will list the missing field(s).

UNKNOWN_FIELDS HTTP 400

The request included a field that is not recognized by the endpoint. The error_message field will list the extraneous field(s).

INVALID_FIELD HTTP 400

One or more of the request body fields was improperly formatted or an invalid type.

INVALID_BODY HTTP 400

The request body was invalid. Only JSON bodies are accepted.

INVALID_HEADERS HTTP 400

The request was missing a required header, typically the Content-Type header.

NOT_FOUND HTTP 404

The endpoint requested does not exist.

SANDBOX_ONLY HTTP 400

The requested endpoint is only available in the Sandbox API environment.

Invalid input errors

Returned when all fields are provided and are in the correct format, but the values provided are incorrect in some way.

Invalid input errors

{
"error_type": "INVALID_INPUT",
"http_code": 400,
"error_code": Enum (
"INVALID_API_KEYS",
"UNAUTHORIZED_ENVIRONMENT",
"INVALID_TOKEN",
"INVALID_PRODUCT",
"INVALID_ACCOUNT_ID",
"INVALID_BANK"
)
"error_message": String
"display_message": Null,
"request_id": String
}

Error Code

Notes

INVALID_API_KEYS HTTP 400

The client token and secret key included in the request body were invalid. Find your API keys in the Dashboard.

UNAUTHORIZED_ENVIRONMENT HTTP 400

Your client token does not have access to this API environment. See which environments you are enabled for from the Dashboard.

INVALID_TOKEN HTTP 400

Access tokens are in the format: access-<environment>-<identifier> This error can happen when the access_token you provided is invalid, from a different API environment, or has been removed via a /record/remove request.

INVALID_PUBLIC_TOKEN HTTP 400

Public tokens are in the format: public-<environment>-<identifier>This error can happen when the public_token you provided is invalid, from a different API environment, or expired.

INVALID_PRODUCT HTTP 400

Your client token does not have access to this product. Contact us to gain access.

INVALID_ACCOUNT_ID HTTP 400

One of the account_id(s) specified is invalid or does not exist.

INVALID_BANK HTTP 400

The bank_id specified is invalid or does not exist.

Rate limit exceeded errors

Returned when the request is valid but has exceeded established rate limits. All API endpoints are rate limited and all data-access endpoints are rate limited by token. Exact limits are dynamic and are designed to prevent any single source of traffic from impacting overall API stability.

{
"error_type": "RATE_LIMIT_EXCEEDED",
"http_code": 429,
"error_code": Enum (
"ACCOUNTS_LIMIT",
"ADDITION_LIMIT",
"AUTH_LIMIT",
"IDENTITY_LIMIT",
"INCOME_LIMIT",
"RECORD_GET_LIMIT",
"RATE_LIMIT"
"TRANSACTIONS_LIMIT",
)
"error_message": String
"display_message": nullable String,
"request_id": String
}

Error Code

Notes

ACCOUNTS_LIMIT HTTP 429

Too many requests were made to the /accounts/getendpoint.

ADDITION_LIMIT HTTP 429

You have exceeded your addition limit in our Development environment. To increase it, or raise it from zero, contact us.

AUTH_LIMIT HTTP 429

Too many requests were made to the /auth/getendpoint.

IDENTITY_LIMIT HTTP 429

Too many requests were made to the /identity/getendpoint.

INCOME_LIMIT HTTP 429

Too many requests were made to the /income/getendpoint.

RECORD_GET_LIMIT HTTP 429

Too many requests were made to the /record/getendpoint.

RATE_LIMIT HTTP 429

Too many requests were made.

TRANSACTIONS_LIMIT HTTP 429

Too many requests were made to the /transactions/get endpoint.

API errors

Returned during planned maintenance windows and in response to API errors.

{
"error_type": "API_ERROR",
"http_code": 500,
"error_code": Enum (
"INTERNAL_SERVER_ERROR",
"PLANNED_MAINTENANCE"
)
"error_message": String
"display_message": nullable String,
"request_id": String
}

Error Code

Notes

INTERNAL_SERVER_ERROR HTTP 500

Okra was unable to process the request, either due to an internal system issue or an unsupported response from a bank.

PLANNED_MAINTENANCE HTTP 500

Okra's systems are in maintenance mode and API operations are disabled. Advanced notice will be provided if a maintenance window is ever planned.

Item errors

A RECORD_ERROR indicates that information provided for the Item (such as credentials or MFA) may be invalid or that the Item is not supported on Okra's platform. You'll encounter RECORD_ERRORs as your users use Link via the onClose() callback.

{
"error_type": "RECORD_ERROR",
"http_code": 400,
"error_code": Enum (
"INVALID_CREDENTIALS",
"INVALID_MFA",
"INVALID_SEND_METHOD",
"INVALID_UPDATED_USERNAME",
"RECORD_LOCKED",
"RECORD_LOGIN_REQUIRED",
"RECORD_NO_ERROR",
"RECORD_NOT_SUPPORTED",
"RECORD_NO_VERIFICATION",
"INCORRECT_DEPOSIT_AMOUNTS",
"TOO_MANY_VERIFICATION_ATTEMPTS",
"USER_SETUP_REQUIRED",
"MFA_NOT_SUPPORTED",
"NO_ACCOUNTS",
"NO_AUTH_ACCOUNTS",
"NO_INVESTMENT_ACCOUNTS",
"NO_LIABILITY_ACCOUNTS",
"PRODUCT_NOT_READY",
"PRODUCTS_NOT_SUPPORTED"
)
"error_message": String
"display_message": nullable String,
"request_id": String
}

Error Code

Notes

INVALID_CREDENTIALS HTTP 400

The bank indicated that the credentials provided were invalid.

INVALID_MFA HTTP 400

The bank indicated that the MFA response(s) provided were invalid.

INVALID_SEND_METHOD HTTP 400

Okra could not match up the MFA OTP send method to one of the ones we sent to the user or the bank rejected it as invalid for some reason.

INVALID_UPDATED_USERNAME HTTP 400

The username provided in update mode via Link did not match the original username for the Item.

RECORD_LOCKED HTTP 400

The bank indicated that the user's account is locked. The user will need to work with the bank directly to unlock their account.

RECORD_LOGIN_REQUIRED HTTP 400

The bank indicated that the user's password or MFA information has changed. They will need to reauthenticate via Link's update mode.

RECORD_NO_ERROR HTTP 400

Link was initialized in update mode for an Item that is in a good state. No further action is required.

RECORD_NOT_SUPPORTED HTTP 400

Okra is unable to support this user's accounts due to restrictions in place at the bank.

RECORD_NO_VERIFICATION HTTP 400

Okra is unable to support this user's accounts due to restrictions in place at the bank.

TOO_MANY_VERIFICATION_ATTEMPTS HTTP 400

The user attempted to verify their Manual Same-Day micro-deposit amounts more than 3 times for an Item. The Item is now permanently locked and the user must retry with a new bank.

USER_SETUP_REQUIRED HTTP 400

The user must log in directly to the bank and take some actions (agree to updated terms and conditions, change their password, etc.) before Okra can access their accounts.

MFA_NOT_SUPPORTED HTTP 400

Returned when the user requires a form of MFA that Okra does not support for a given bank.

NO_ACCOUNTS HTTP 400

Returned when there are no open accounts associated with the Item.

NO_AUTH_ACCOUNTS HTTP 400

Returned from POST /auth/get when there are no valid checking or savings account(s) for which account and routing numbers could be retrieved.

PRODUCT_NOT_READY HTTP 400

Returned when a data request has been made for a product that is not yet ready. This primarily happens when attempting to pull transactions prior to the initial pull.

PRODUCTS_NOT_SUPPORTED HTTP 400

Returned when a data request has been made for an Item for a product that it does not support. Use the /item/get endpoint to find out which products an Item supports.

Auth errors

The AUTH_ERROR error type identifies a class of issues related to verifying and pulling Auth numbers data.

{
"error_type": "AUTH_ERROR",
"http_code": Enum (
400,
404,
500
),
"error_code": Enum (
"PRODUCT_NOT_READY",
"VERIFICATION_EXPIRED"
),
"error_message": String,
"display_message": nullable String,
"request_id": String,
"account_id": String
}

Error Code

Notes

PRODUCT_NOT_READY HTTP 400

Calling /auth/get on an Item that has not been verified will return this error. Verify the Item manually, or wait for automated verification to succeed.

VERIFICATION_EXPIRED HTTP 400

If an Item cannot be verified after 7 days, an error webhook will be sent to the webhook specified in the Link configuration

Bank errors

Returned when there are errors for the requested bank.

{
"error_type": "BANK_ERROR",
"http_code": 400,
"error_code": Enum (
"BANK_DOWN",
"BANK_NOT_RESPONDING",
"BANK_NOT_AVAILABLE",
"BANK_NO_LONGER_SUPPORTED"
)
"error_message": String
"display_message": nullable String,
"request_id": String
}

Error Code

Notes

BANK_DOWN HTTP 400

The financial institution is down, either for maintenance or due to an infrastructure issue with their systems.

BANK_NOT_RESPONDING HTTP 400

The financial institution is failing to respond to some of our requests. Your user may be successful if they retry another time.

BANK_NOT_AVAILABLE HTTP 400

The financial institution is not available this time.

BANK_NO_LONGER_SUPPORTED HTTP 400

Okra no longer supports this financial institution.

Widget errors

Errors returned on the widget.

Widget errors

{
"type": "error",
"status": false,
"code": 1013,
"method": "Insufficient Funds - Direct Debit",
"message": "There are insufficient funds in this account to make this debit."
}

Error Code

Method

Message

INVALID_REQUEST 1000

Validation

Validation failed, please confirm credentials and try again.

ERROR CODE 1002

Transactions Fetch Error

Unable to fetch transactions. Please try again.

ERROR CODE 1003

Balance Fetch Error

Unable to fetch balance. Please try again.

ERROR CODE 1004

No Plan

Please visit the plans page to select a plan.

ERROR CODE 1005

Wallet Insufficient Funds

Please visit the wallet page to top-up your wallet.

ERROR CODE 1006

Invalid API credentials

Please visit the API keys page to get your API credentials

ERROR CODE 1007

Plan expired, or Free Calls Exhausted

If you're on Start Up, please upgrade your plan here. If you're on Volume or PAYG, please top-up your wallet here.

ERROR CODE 1008

Data Extraction

Data fetched was not available on selected Bank - Please Retry.

ERROR CODE 1009

Validation

Validation error, please confirm credentials and try again.

ERROR CODE 1010

Invalid Token

You entered invalid token credentials, please check your token and try again!

ERROR CODE 1011

Invalid Security Question

You entered and invalid secret question answer, please try again!

ERROR CODE 1012

Processed Killed

Your session was terminated due to inactivity, please retry!

ERROR CODE 1013

Insufficient Funds - Direct Debit

There are insufficient funds in this account to make this debit.

ERROR CODE 1026

SLA Error

You are yet to sign your SLA, please reach out to the Sales team for help.