Error Codes

When a gPRC call completes successfully, the server returns an OK status to the client (depending on the SDK language, the OK status may or may not be directly used in your code). If a call isn’t successful, gRPC returns one of its error status codes instead, with an optional string error message that provides further details about what happened. Error information is available to gRPC clients in all supported languages. For more on the gRPC protocol, see gRPC and Protocol Buffers in Token.io Basics.

A "bank error" (an error occurring during bank processing of a TPP request) will have a gPRC error code of 12, which means the payment or account information access operation requested is not currently supported/implemented by the bank. Such conditions can be avoided with more granular filtering of bankfeatures using the getBanks() method discussed in Filtering Banks for User Selection .

gRPC Errors

Token.io's APIs both throw the following standard gRPC exceptions (enum names can be seen in the respective stack dumps):

List of Exceptions
Error Enum	Value	Meaning
OK	0	Operation completed successfully
canceled	1	Operation was canceled; typically, by the caller
UNKNOWN	2	Unknown error; e.g., a status value was received from an unknown error space or an API call returned an error with incomplete information. A special case that will generate an Error 2 is when an access_denied status is returned by the bank. This invariably occurs when the user cancels, rejects, or otherwise fails to give consent and authorization approval to the bank for the TPP's request.
INVALID_ARGUMENTS	3	Client specified an incomplete argument
DEADLINE_EXCEEDED	4	Deadline expired before operation could complete
NOT_FOUND	5	Requested entity, such as a file or directory, was not found
ALREADY_EXISTS	6	Attempt to create entity, such as a file or directory, that already exists
PERMISSION_DENIED	7	Caller does not have the required permission to execute the operation specified. This error message will be accompanied by the reason from the bank. Typically means the access token has expired and the TPP needs its user to re-authenticate with the bank
RESOURCE_EXHAUSTED	8	Resource, such as a per-user quota or file system, is exhausted (out of space)
FAILED_PRECONDITION	9	Operation rejected because the current system state cannot support execution
ABORTED	10	Operation aborted; typically, a concurrency issue is the cause
OUT_OF_RANGE	11	Operation attempted exceeds the valid range; e.g., seeking or reading past EOF
UNIMPLEMENTED	12	Operation not implemented / supported / enabled
INTERNAL	13	Internal error (see alert below)
UNAVAILABLE	14	Service unavailable, likely due to a transient condition; usually corrected with a retry
DATA_LOSS	15	Unrecoverable data loss or corruption
UNAUTHENTICATED	16	Request does not have valid authentication credentials needed to perform the operation

If you receive an internal server error (HTTP 500 or an rpc status = INTERNAL), this could refer to either an error on Token.io’s end or an error on the bank’s end.

When the bank reports a 5xx error, Token.io sets token-external-error=true as a header in the HTTP response, indicating that the "internal" error originates from the bank. When one of Token.io's internal services fails or when the bank reports a 4xx error, this header is not populated.

The absence of this response header should be interpreted as token-external-error=false.

JavaScript Errors

Token.io's JavaScript SDK throws standard HTTP errors. All errors are wrapped in an error object with a message that contains the SDK method that failed, accompanied by the reason for the failure.