Bank Account Data - Statuses and Error Messages
Statuses and Error Messages
Learn about status and error messages for different Bank Account Data endpoints.
Statuses
Learn more about each state for requisitions and accounts.
Requisitions endpoint
Status short | Status long | Description | Stage* |
|---|---|---|---|
CR | CREATED | Requisition has been successfully created | 1 |
GC | GIVING_CONSENT | End-user is giving consent at GoCardless's consent screen | 2 |
UA | UNDERGOING_AUTHENTICATION | End-user is redirected to the financial institution for authentication | 3 |
RJ | REJECTED | Either SSN verification has failed or end-user has entered incorrect credentials | 4 |
SA | SELECTING_ACCOUNTS | End-user is selecting accounts | 5 |
GA | GRANTING_ACCESS | End-user is granting access to their account information | 6 |
LN | LINKED | Account has been successfully linked to requisition | 7 |
EX | EXPIRED | Access to accounts has expired as set in End User Agreement | 8 |
*describes sequence for each possible status, where “1” is starting status.
Accounts endpoint
Status long | Description |
|---|---|
DISCOVERED | User has successfully authenticated herself, and account has been discovered |
ERROR | An error was encountered when processing account |
EXPIRED | Access to account has expired as set in End User Agreement |
PROCESSING | Account is being processed by the institution |
READY
| Account has been successfully processed |
SUSPENDED | Account has been suspended (more than 10 consecutive failed attempts to access the account) |
End user authentication messages
STATUS | DESCRIPTION | HTTP status |
|---|---|---|
InstitutionTechnicalError | A technical error occurred while trying to connect to the institution, please try again. | 500 |
GoCardlessTechnicalError | An unexpected error occurred in the GoCardless system. If this error persists, please contact support. | 500 |
RequisitionLinkReused | This link has already been used for authorization and is no longer valid. | 400 |
UserCancelledSession | User cancelled the session. | 401 |
UserSessionRejected | User session rejected due to incorrect credentials or a business exception. | 401 |
UnknownError | An unknown error occurred. |
|
API Messages
All error HTTP codes will be 4xx or 5xx, so we recommend using success http codes for the control flow and the error messages for informative purposes. If an error has occurred, it will be displayed in the following form:
{ "summary": "Unknown institution ID", "detail": "Get institution ID from /institutions/?country={country_code}", "status_code": 400 }
Institutions endpoint
Summary | Detail | HTTP status |
|---|---|---|
Unknown fields {fields} in the payload |
| 400 |
Invalid token | 401 |
Agreements endpoint
Summary | Detail | HTTP status |
|---|---|---|
Incorrect max_historical_days | max_historical_days must be > 0 and <= {institution_id} transaction_total_days (int) | 400 |
End User Agreements cannot be accepted more than once |
| 400 |
Cannot delete End User Agreement | Cannot delete accepted End User Agreement: {eua_id}. Only non-accepted agreements can be deleted | 400 |
Invalid token | 401 |
Requisitions endpoint
Summary | Detail | HTTP status |
|---|---|---|
Invalid redirect URI | Redirect URI must have a valid URI structure" | 400 |
Invalid EUA | {agreement_id} is not a valid UUID. Please specify valid agreement from /api/agreements/enduser/?={enduser_id} or create a new one | 400 |
Incorrect enduser_id | enduser_id in requisition have to be the same as specified in EUA {eua_id}. Requisition enduser_id: " {req_enduser_id}, EUA enduser_id {eua_enduser_id} | 400 |
Provided user_language is invalid or not supported | {user_language} is invalid or not supported language | 400 |
Invalid token | 401 |
Accounts endpoint
Summary | Detail | HTTP status |
|---|---|---|
Invalid Account ID | {id} is not a valid UUID | 400 |
End User Agreement (EUA) {eua_id} has expired | EUA was valid for {valid_days} days and it expired at {expired_date}. The end user must connect the account once more with new EUA and Requisition | 400 |
AccessExpiredError | Access has expired or it has been revoked. To restore access reconnect the account | 401 |
AccountInactiveError | Account has been deactivated or it no longer exists | 401 |
Invalid token |
| 401 |
AccountAccessForbidden | Access to the account is forbidden, the user might not have the necessary permissions | 403 |
Account Suspended | This Account or its Requisition was suspended due to numerous errors that occurred while accessing it | 409 |
AccountProcessing | Your account data is currently being processed. Please try again shortly, or poll /accounts/{account_id}/ endpoint and retry when status is READY | 409 |
RateLimitError | The daily request limit set by the Institution has been exceeded | 429 |
UnknownRequestError | Request to institution returned an unknown error | 500 |
ServiceError | Institution service unavailable | 503 |
ConnectionError | Couldn't connect to Institution | 503 |