Proposal: Define ILP Errors

[emschwartz]

Right now we have the concept of a "rejection reason" when transfers are rejected, but those messages are neither well-defined nor relayed backwards by connectors.

We should define:

• ILP error codes/types
• Whether additional information can be added (e.g. for debugging purposes)
• Which error codes are final and which indicate a payment should be retried

Here's a first stab at some error cases:

Connector rejected payment

• ledger unresponsive
• insufficient liquidity
• insufficient timeout window
• unable to route payment
• temporarily overloaded
• ledger doesn't accept crypto condition
• receiver let payment time out (don't know why)
• invalid packet

Receiver rejected payment

• insufficient amount
• invalid packet
• other error (don't retry) - do we want to include a message?
• account doesn't exist (?)
• account cannot accept payment (over transaction or balance limit?)

These cannot necessarily be "trusted", because a connector relaying the message back could modify it, but it still seems helpful for development purposes at least.

[adrianhopebailie]

Do we want to include regulatory stuff? Maybe just a generic transfer not permitted or similar?

[emschwartz]

ILP 451

[sharafian]

I think ILP error messages should also have some indication of what component is rejecting the transfer. A rejecting coming from the ILP Kit API is different from a rejection coming from the ILP Connector, and in the case where both are listening on an account it can help diagnose problems.

[adrianhopebailie]

I think ILP error messages should also have some indication of what component is rejecting the transfer.

Where possible this would be great but I would be wary of making it a hard requirement until we are certain it can be done (i.e. the information is (and should be, privacy etc considered) available at the end-point where the error is handled)

[emschwartz]

From @justmoon:

Let's make sure all ILP rejections always include the ILP address and component type (connector, ledger, plugin, receiver, application-layer, app) of whatever component rejected it.

[justmoon]

@sentientwaffle wrote up a proposal: https://gist.github.com/sentientwaffle/ce5af28f16c26f35c453a7b7078e4edf

[justmoon]

I like in HTTP that we can look at the first digit of the error code to figure out what to do:

• 1xx Informational --> Just to let you know...
• 2xx Success --> You're good!
• 3xx Redirection --> Go over here!
• 4xx Client Error --> You messed up, probably not worth retrying unless you change the request you made.
• 5xx Server Error --> Try again later!

This is an error categorization that is actually useful!

I wonder if it should really be just a rejection mechanism or just a general status mechanism... maybe it'd be nice if I got a reply from the connector when they forwarded the payment. Might be too noisy, but could help debugging.

In our case, I can see the following categories (using @emschwartz' list in the original issue as a starting point):

• S__ - Sender Error

  (You messed up, probably not worth retrying unless you change what you sent.)

  • S00 - Bad Request - Generic sender error.
  • S01 - Invalid Packet - The ILP packet was syntactically invalid.
  • S02 - Unreachable - There was no way to forward the payment, because the destination ILP address was wrong or unreachable.
  • S03 - Invalid Amount - The amount is invalid, e.g. it contains more digits of precision than are available on the destination ledger or the amount is greater than the total amount of the given asset in existence.
  • S04 - Insufficient Destination Amount - The amount was insufficient given the memo. E.g. you tried to pay a $100 invoice with $10.
  • S05 - Wrong Condition - The receiver generated a different condition and cannot fulfill the payment.
  • S06 - Unexpected Payment - The receiver was not expecting a payment like this (the memo and destination address don't make sense in that combination.)
  • S07 - Cannot Receive - The receiver is unable to accept this payment due to a constraint, e.g. a limit was exceeded.

• T__ - Temporary Error

  (Something failed and it's not your fault. You should try the same thing again later.)

  • T00 - Internal Error - Like HTTP 500. Something threw an exception - that's all we know. Try again later after we've had time to fix it.
  • T01 - Ledger Unreachable - The connector was not able to reach the next ledger. Try again later.
  • T02 - Ledger Busy - The ledger is rejecting requests due to overloading. Try again later.
  • T03 - Connector Busy - The connector is rejecting requests due to overloading. Try again later.
  • T04 - Insufficient Liquidity - The connector would like to fulfill your request, but it doesn't currently have enough money. Try again later.

• R__ - Relative Error

  (Something failed, but it's impossible to tell if the sender didn't provide enough error margin or whether the path just got slow/dry all of the sudden. You should maybe try again, but with a bigger safety margin.)

  • R01 - Transfer Timed Out - The transfer timed out, i.e. the next party in the chain did not respond. This could be because you set your timeout too low or because something look longer than it should. Try again with a higher expiry.
  • R02 - Insufficient Source Amount - Either you didn't send enough money or there wasn't enough liquidity. Try again with a higher sending amount.
  • R03 - Insufficient Timeout - The connector could not forward the payment, because the timeout was too low to subtract its safety margin. Try again with a higher expiry.

This is not meant to final obviously. Let us know what you would add/remove/change!

[earizon]

I just updated a old (java) mini-library I've been using for years (and that has always worked really well for me) that can inspire another point of view about error control. It put the emphasis on the external entity that will be in charge of fixing the errors, instead of the source of the error. Once the code has enought information to know who must take charge it forgets (since actually the code can't make anything to fix the error). https://github.com/earizon/java_recipient_exceptions/blob/master/README.md I think adding an minimal codification to classify error codes (4xx, 5xx,....) is something useful, but the extra xx is usually not since such extra codes must in the end be interpreted by humans. A single english plain text (probably wrapped in a JSON object,....) is ussually more descriptive. Since errors are supposed to be the exception, not the norm, the extra bytes makes not much difference in terms of performance and give freedom to developers to trigger as much different errors as desired, with different degree of details, without being constrained to a previous API. (error codes can still be useful, but not mandatory). Also system administrators will apreciate not having to search in tons of manuals the meaning of an error code while the system is down and the storm approach. For GUI designers it will also be easier to just display on the screen the human text received, with no extra efforts to interpret the meaning of the error.

[sappenin]

Not sure if it's exactly something we want to duplicate, but there's some prior art (or at least, an attempt at prior art) when it comes to defining errors for HTTP Apis: https://tools.ietf.org/html/rfc7807

I'm not sure how popular it is, but at a prior company I worked at, we were exploring a move to this standard for our API error messages. There's a java implementation here that works quite well: https://github.com/zalando/problem

I understand the desire to de-couple ILP error codes from HTTP, so maybe a mapping from standard ILP error codes to HTTP error codes might be appropriate (or maybe a way to wrap ILP error codes in an HTTP/JSON format?)

[emschwartz]

I think we definitely want to decouple ILP errors from HTTP because much of the time they won't actually be sent over HTTP anyway.

We need some format for errors, like we needed some format for the ILP packet. However, the requirements for errors are a bit different than for the packet:

• Text > binary, because part of the purpose of errors is communicating to developers what went wrong
• Need error codes, but most of the error message should be customizable by the transport or application layers
• We might want to have connectors include their ILP addresses in the error message as they're forwarding it and they shouldn't need to decode the whole message to do so
• We might want application-layer errors to be encrypted if they can be, for example using PSK

The options I see are:

• Custom text format, like what I started writing up in the first draft of the spec
• JSON
• HTTP-formatted headers + data
• something else

For the HTTP-formatted headers + data, the idea is not to use HTTP error codes or to make it dependent on HTTP, but just to use the data format in the same way we're using it for PSK. Something like:

ILP/1.0 S00: Bad Request
Triggered-By: example.ledger.bob
Forwarded-By: example.connector.connie,example.connector.chloe
Date: 2017-03-23T00:00:00Z
Content-Type: application/json

{
  "id": "SomeApplicationError",
  "message": "Oops..."
}

Side note: I wonder if these errors should be thought of as "ILP errors", or being on the transport layer, or on an orthogonal plane (kind of like quoting a routing).