error-codes.md

Error codes

The 40 error codes the API can return, live from https://api.wealthreader.com/error-codes/. Add ?lang=en for English, omit it for Spanish.

The retry decision

Each code carries a fatal flag, and it is the only thing that decides whether retrying makes sense:

• fatal: true — the call will fail again with the same input. Retrying wastes a request and, for credential errors, walks the user towards a locked account at their bank. Surface it and stop.
• fatal: false — transient. Back off and retry, or let the next scheduled run pick it up.

18 of the 40 codes are fatal.

Do not retry (fatal: true)

Code	Meaning	Why it happens	What to do
3	Blocked token	The token has been blocked, due to a fatal error (For example, invalid credentials, when the user has changed them)	You must generate a new token
2000	Login incorrect	Some of the login data is incorrect	If this is an interactive login, ask the user to correct the error. If the error is obtained in a batch, mark that user as invalid so as not to retry the login and cause the user's credentials to be blocked in the entity
2001	User blocked	User is locked out	If this is an interactive login, ask the user to unlock the user in their online banking. If the error is obtained in a batch, mark that user as invalid so as not to retry the login
2004	Error in logging into the entity, offer an alternative connection method, after which the user must wait 24 business hours before attempting the connection again.	This will occur when the primary connection to the required banking entity fails.	The user should connect using the alternative method, wait for 24 business hours, and then make a new connection attempt.
2012	Push notification not yet received	The user has not yet accepted the login request received on his device	Ask the user to accept the login request received on their device
2015	Two-factor challenge not completed on time	A second API call has been sent after a two-factor challenge from the entity, exceeding the maximum time set by the entity to complete it	Ask the user to start the login process again
2018	Selected two-factor method does not exist	The entity offers multiple two-factor methods and the user must select one, but the selected method does not exist	Ask the user to select an existing two-factor method
2020	Multi-contract user. The error code will be accompanied by a contract_names object with the available contracts, the structure of which is described in the models in the documentation	The login credentials are correct, but the user has more than one contract and must select one. This is common for users managing company accounts	You need to specify a value for contract_name in the API call
2030	Script type two-factor challenge, may require extension installation	The entity requires a second authentication factor with code interpretation in the client's browser.	Ask the user to install the required extension and follow the instructions through the integration widget.
2070	OAuth authentication is required	The entity requires the user to complete the OAuth flow to proceed	Redirect the user to the OAuth flow and obtain the corresponding token
9999	Token invalidated by client request	The client has invalidated this token with the API's informed method (Manual)	The client must generate a new token
20101	OTP (One Time Password) two-factor challenge	The entity requires a second authentication factor	Ask the user to reauthenticate to revalidate the token.
20111	Push type two-factor challenge	Entity requires second factor authentication	Ask the user to reauthenticate to revalidate the token.
20131	OTP (One Time Password) two-factor challenge, scan the image with the mobile application, and enter the code.	The entity requires a second authentication factor	Ask the user to reauthenticate to revalidate the token.
20141	Push type two-factor challenge, scan the image with the mobile application, accept the notification, and continue.	Entity requires second factor authentication	Ask the user to reauthenticate to revalidate the token.
20161	Push notification and/or OTP code	Entity prompts the user to press PUSH on the APP or enter an OTP code	Ask the user to accept the login request received on their device or enter the OTP code received
20171	Two-factor method selection	The entity offers multiple two-factor methods and the user must select one	Ask the user to select a two-factor method
20191	URL type two-factor	The entity requires a second authentication factor, you will receive a message to your associated device, with a URL to complete the process	Ask the user to copy the link received, without using it, and send it as OTP

Safe to retry (fatal: false)

Code	Meaning	Why it happens	What to do
1	Generic error	An error not covered by the other error codes	Open a ticket stating the value of statistics.SESSION
2	Incorrect call	Some of the required parameters were not sent, were sent in an incorrect format, a usage limit has been exceeded, or a product type not allowed by the license has been requested	The text received in "message" will detail the reason for the error. For example, "The parameter 'api_key' is required"
4	Temporarily invalid token	A two-factor challenge or a temporary error requires generating a new token, but it is not a definitive failure	Wait a few minutes or resolve the challenge (for example, an OTP code), and try again. Generate a new token if necessary
1000	Error getting data obtained from entity	The entity has changed its structure	Open a ticket indicating the value of statistics.SESSION
1001	Error formatting data obtained from entity	The entity has changed its structure	Open a ticket indicating the value of statistics.SESSION
2002	User not accessible	The login data is correct, but the user does not have access to the data because it is pending activation	The text received in "message" will detail the reason why the user cannot access: he must update his ID, must sign some document, etc
2003	The client does not have the contracted product	This will happen when the client provides valid login credentials but does not have the product requested contracted. This message will be received instead of an empty payload to distinguish it from a potential error.	The text received in "message" will inform the client that they do not have the product requested contracted, so they can take appropriate action.
2005	There is already an active session for this user. Try again later.	This error occurs when simultaneous connections are detected for the same user in our API. To avoid conflicts, the API blocks multiple parallel connections.	Wait for the current active session to end before trying to connect again. If you cannot verify the session status, retry the connection at time intervals, such as every 5 minutes.
2010	OTP (One Time Password) two-factor challenge	The entity requires a second authentication factor	If this is an interactive login, ask the user to enter the code received on his device. If the error is obtained in a batch, mark that user as invalid so as not to retry the login in the following days
2011	Push type two-factor challenge	Entity requires second factor authentication	If this is an interactive login, ask the user to enter the code received on their device. If the error is obtained in a batch, mark that user as invalid so as not to retry the login in the following days
2013	OTP (One Time Password) two-factor challenge, scan the image with the mobile application, and enter the code.	The entity requires a second authentication factor	If this is an interactive login, ask the user to enter the code received on his device. If the error is obtained in a batch, mark that user as invalid so as not to retry the login in the following days
2014	Push type two-factor challenge, scan the image with the mobile application, accept the notification, and continue.	Entity requires second factor authentication	If this is an interactive login, ask the user to enter the code received on their device. If the error is obtained in a batch, mark that user as invalid so as not to retry the login in the following days
2016	Push notification and/or OTP code	Entity prompts the user to press PUSH on the APP or enter an OTP code	Ask the user to accept the login request received on their device or enter the OTP code received
2017	Two-factor method selection	The entity offers multiple two-factor methods and the user must select one	Ask the user to select a two-factor method
2019	URL type two-factor	The entity requires a second authentication factor, you will receive a message to your associated device, with a URL to complete the process	Ask the user to copy the link received, without using it, and send it as OTP
2050	Image captcha challenge	The entity requires the user to manually input a code from an image captcha.	Ask the user to solve the image captcha and input the code as instructed.
2051	Coordinate-based captcha challenge	The entity requires the user to select specific coordinates in an image as part of the authentication process.	Ask the user to select the correct coordinates in the image as instructed.
2052	Puzzle captcha challenge	The entity requires the user to complete a puzzle to verify authentication.	Ask the user to solve the puzzle challenge as instructed.
2053	Audio captcha challenge	The entity requires the user to listen to an audio file and input the spoken code.	Ask the user to listen to the audio and enter the correct code as instructed.
3000	Entity under maintenance	The entity's online access is under maintenance	This is a known, temporary problem. Please retry after a few minutes
3001	Execution time exceeded	Server down or delayed	This is a known, temporary problem. Please retry after a few minutes
3002	Connection with the entity is under maintenance.	The entity is performing maintenance tasks on its online banking system, or has made changes to its data structure. We are in the process of adjusting it.	This is a known, temporary problem. Please retry after 24 business hours.

The error object arrives as error.code and error.message. In an iframe integration the widget resolves most of these with the user directly and your callback is never called; the codes matter most when you call the API yourself with a stored token.