The Token.io platform supports the following error codes:
-
HTTP
-
gPRC
-
JSON
HTTP errors
The following table gives a general description of the possible HTTP status codes that could be returned in response to API requests to the Token.io platform. These statuses could be related to business logic or system errors.
| Response | Description |
| 400 |
Bad request (INVALID_ARGUMENT), likely client error: |
| 401 |
Unauthorised request: The request does not have valid authentication credentials needed to perform the operation. |
| 403 |
Forbidden request/Permission denied: The error returned when the member is not authorized to perform the given operation: PermissionDenied. This error message will be accompanied by the reason from the bank. Typically this means the access token has expired and the TPP needs the user to re-authenticate with the bank. |
| 404 |
Resource in request not found: The error object returned when given payment cannot be found. |
| 429 |
Too many requests: Resource exhausted. |
| 500 |
An unexpected or internal server error: This could refer to either an error on Token.io’s end or an error on the bank side. When the bank reports a 5xx error, Token.io sets |
| 501 |
The operation was not implemented (unimplemented): The operation was not implemented/supported/enabled by the bank. |
| 503 |
Service is unavailable: Service is unavailable, likely due to a transient condition; this is usually corrected with a retry. |
| 504 |
Gateway has timed out: The deadline expired (DEADLINE_EXCEEDED) before the operation could complete. |
gPRC errors
When a gPRC call completes successfully, the server returns an OK status to the client.
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.
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 bank features using GET v2/banks.
|
Error Enum |
Value |
HTTP |
Meaning |
|---|---|---|---|
OK |
|
|
Operation completed successfully |
CANCELED |
|
|
Operation was cancelled; typically, by the caller |
UNKNOWN |
|
|
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 |
INVALID_ARGUMENTS |
|
400 |
Client specified an incomplete argument |
DEADLINE_EXCEEDED |
|
504 |
Deadline expired before operation could complete |
NOT_FOUND |
|
404 |
Requested entity, such as a file or directory, was not found |
ALREADY_EXISTS |
|
409 |
Attempt to create entity, such as a file or directory, that already exists |
PERMISSION_DENIED |
|
403 |
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 |
|
429 |
Resource, such as a per-user quota or file system, is exhausted (out of space) |
FAILED_PRECONDITION |
|
400 |
Operation rejected because the current system state cannot support execution |
ABORTED |
|
|
Operation aborted; typically, a concurrency issue is the cause |
OUT_OF_RANGE |
|
400 |
Operation attempted exceeds the valid range; e.g., seeking or reading past EOF |
UNIMPLEMENTED |
|
501 |
Operation not implemented / supported / enabled |
INTERNAL |
|
500 |
Internal error (see alert below) |
UNAVAILABLE |
|
503 |
Service unavailable, likely due to a transient condition; usually corrected with a retry |
DATA_LOSS |
|
|
Unrecoverable data loss or corruption |
UNAUTHENTICATED |
|
401 |
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".
JSON format
If you'd prefer to receive error responses in JSON format, you can read more in our developer documentation.