Arguably, one use case for the low-level sendpay interface is to have the caller create its own routes using its own routing algorithms. However if sendpay fails the caller would need to know exactly how it failed --- what onion reply failcode was returned, who returned it, what channel was it referring to.

Thus for sendpay failures we need to provide detailed code:

• -1 Catchall nonspecific error
• -2 A previous pay or sendpay is still in progress.
• -3 Already paid with this rhash.
• -4 Unparseable onion reply. Caller should try a completely different route. There will be a data field, an object with the single field onionreply which contains the reply as hex.
• -5 Non-retryable routing error. Permanent error at the payee. There will be a data field, with a routing-failure object.
• -6 Retryable routing error. Caller should try an alternate route. There will be a data field, with a routing-failure object.

A routing-failure object contains:

• origin_index the index on the route of the node which failed. 0 for the first node, and so on, or -1 if the local node failed (e.g. not enough capacity on the channel to the first hop node). This is provided in case the caller makes a route that passes through the same node multiple times.
• erring_node the pubkey id of the indicated node as a hex string.
• erring_channel the short channel id of the channel after the indicated node. Not present if origin_index points to the last (payee) node.
• failcode the failure code as a JSON number. Refer to BOLT4.
• channel_update the channel update message from the failing node, if failcode has UPDATE bit set (refer to BOLT 4) and origin_index is not -1 (the local node), as a hex string.