Getting Started - Best Practices for Timeouts and Retries
Timeouts and Retries for API Calls
The recommended timeout for API calls is 10 seconds (both POST and GET).
API GET Calls
GET calls are waiting/blocking for a final check status at a maximum of 5 seconds. If a final status is not available within this time, a status IN_PROGRESS will be returned as part of the response object.
The calling party shall retry the GET call in this case.
For GET calls, the recommended number of at least 3 retries.
When to give the User the Option to Retry the Check
Humans are prone to errors; the user may enter faulty data during the identity check process, like
misspelt names, addresses, ZIP codes,
wrong banking credentials,
invalid second-factor code,
use a login to a bank, where he has no checking account.
As a consequence, either the bank login may fail, or one of the SCHUFA services may return a result, that is not acceptable.
Failures in the bank login process are indicated to the user by the finAPI web form, potential issues have a wide variety, thus GiroIdent does not return error codes, but only an error string for debugging purposes - not intended to be shown to the user, as he is informed via web form GUI.
After successful login, the name validation will be performed, additionally, the result of the SCHUFA services will be gathered. GiroIdent does not disclose personal information, therefore details or hints related to which information is not accepted will not be provided on the API / to the user.
We recommend that your application allow the user (at least) one more attempt. It should be the user’s choice to retry, as he received human-readable information either on the finAPI web form or on his bank's login page in case of a redirect. There are no reasonably suitable or meaningful criteria to conditionally allow such an attempt.
Understanding Error Messages
As mentioned above, the error message returned by the GiroIdent API is only debugging information, no application logic shall be implemented based on it, and it shall not be printed on the UI.
Some typical error messages are:
if the user has not finished the web form, the message may contain error codes like
INTERRUPTED,EXPIRED, orABORTED,if the user has entered the wrong credentials or a wrong TAN, the code
BANK_SERVER_REJECTION,other errors (and codes) are technical errors, related to the wrong configuration (typically during integration) or temporary issues of a web service at finAPI, SCHUFA or the bank side.