[Bitcoin-development] Error handling in payment protocol (BIP-0070 and BIP-0072)

J Ross Nicoll jrn at jrn.me.uk
Fri Apr 25 19:54:05 UTC 2014

Dear Gavin, all,

Going over the payment protocol specifications, I've noticed that
there's appears to be a lack of specificity on handling of error states.
In most cases there are reasonably obvious solutions, however it would
seem positive to formalise processes to ensure consistency. I'm
wondering therefore if either you'd be willing to edit the existing BIP,
or advise on whether this is useful to write up as a new BIP?

The main area of concern is handling unexpected problems while sending
the Payment message, or receiving the corresponding PaymentACK message.
For example, in case of a transport layer failure or non-200 HTTP status
code while sending the Payment message, what should the wallet software
do next? Is it safe to re-send the Payment message? I'd propose that for
any transport failure or 500 status code, the client retries after a
delay (suggested at 30-60 seconds). For 400 status codes, the request
should not be repeated, and as such the user should be alerted and a
copy of the Payment message saved to be resent later.

For 300 (redirect and similar) status codes, is it considered safe to
follow redirects? I think we have to, but good to make it clear in the

On the merchant's side; I think it would be useful for there to be
guidance for handling of errors processing Payment messages. I'd suggest
that Payment messages should have a fixed maximum size to avoid merchant
systems theoretically having to accept files of any size; 10MB would
seem far larger than in any way practical, and therefore a good maximum
size? A defined maximum time to wait (to avoid DDoS via connection
holding) might be useful too, although I'd need to do measurements to
find what values are tolerable.

I would like to have the protocol state that merchant systems should
handle repeatedly receiving the same Payment message, and return an
equivalent (if not identical) PaymentACK to each. This is important in
case of a network failure while the client is sending the Payment
message, as outlined above.

Lastly, I'm wondering about potential timing issues with transactions;
if a merchant system wants to see confirmation of a transaction before
sending a PaymentACK, any thoughts on whether it should hold the
connection, or send a PaymentACK with a memo indicating payment has been
seen on the relay network but is not yet confirmed, or something else?

Happy to write this up as a new BIP if that's more appropriate than
editing the original, and please do tell me if I've missed anything
obvious/prior discussion on this topic.


More information about the bitcoin-dev mailing list