No clear indication of possible error cases for submitTransaction

[TorstenStueber]

Is your feature request related to a problem? Please describe. The documentation for submitTransaction does not clearly indicate the possible error scenarios and results. I particularly refer to a timeout error from horizon, i.e, a 504 status with "title": "Timeout". The only mention of this error I found is here and here. The former is very hidden and the latter is part of the official SDK documentation but it is stated in a way that it suggests that this error only needs to be treated if setTimeout is used – which is not true. This error can happen for every submitted transaction.

This error is rather fatal: in a scenario where someone implements Stellar channels and is not aware that this 504 error needs to be treated in a specific way, a failed transaction might be given back to a pool of source accounts and be retried with a different source account and therefore a fresh sequence number. Then, e.g., a payment transaction is executed repeatedly unbeknown to the implementor.

Describe the solution you'd like Describe all possible error scenarios for submitTransaction and how to treat them appropriately. This should also be added to the horizon API documentation or refer to it. Such a description of error scenarios should preferably be added to the other API requests to horizon, too.

[ire-and-curses]

To help us understand:

1. Is the main issue that the info is missing from the JS API docs?
2. Did you see this page? https://www.stellar.org/developers/horizon/reference/errors/timeout.html Is there info that is missing there that you would have benefited from?