A single exception type is not enough

[ghola]

Easypost API requests can lead to (at least) two major error types:

• Network related errors - DNS resolving, connection, transfer, etc. ... this would include the network errors Easypost encounters while calling the carrier APIs.
• Any other error - data validation errors for example

A client encountering a network related error should retry the request but should not retry it for data validation errors. Currently there is no way a client can differentiate between these error types as there is a single Exception class. So given a background process (or daemon) for address validation or label purchasing, that process is required to keep retrying regardless of the error it encounters. The alternative to that is to detect the error type by parsing the exception message, but that would be a very bad practice, nevermind an almost impossible task since we have no way of knowing all the errors that can appear.

I'm sure you can see how this is a waste of resources for all parties involved, and that letting the client know when to retry (and possibly with what delay) is rather essential.

[sawyer]

This is a good idea, we could likely retain the \EasyPost\Error object and give them specific ecodes that relate to network errors. Right now \EasyPost\Requestor.php has a function named handleCurlError which deals with connection errors - it would be relatively simple to give those EasyPost style error codes (NETWORK.TIMEOUT, NETWORK.FAIL, NETWORK.SSL_FAIL, etc) which could be keyed off of in client scripts.

[ZacharyDuBois]

We definitely need more than one exception. Listening for a single exception and having to parse out the message is a very bad way to do things.

[Justintime50]

@ZacharyDuBois totally agree! Thanks for the feedback. We plan to revisit our error handling across all our libraries in the coming weeks/months. I don't have a solid ETA for you; however, this is one of the higher items on our priority list that we want to handle holistically. Keep an eye on this issue for more updates.

[katillery]

Hi, I might be late on the bandwagon here, but I just discovered that if you catch(\EasyPost\Error $e), the result can sometimes be an Easypost error object containing a jsonBody as per the API documentation, and other times (such as if the error is "No rates found"), the object returned does not comport to the documentation specifications, and the message is not even accessible (If I try echo $e->code, I get the following error: “Cannot access protected property EasyPostError::$code”.).

To me, it breaks common sense that the caught \EasyPost\Error $e can be completely differently structured depending on the type of error encountered.

Hoping this makes sense. Thanks!

[Justintime50]

Totally agree! This is the next item I'm picking up most likely at the end of this month. We plan to cut a new major release of this library that will contain a complete overhaul of error handling much like we've recently done in our Java and C# libraries. I'll keep you posted with my progress here.