Throw specific exceptions with decoded responses

[jonathanjfshaw]

Issue	Metadata
Type	feature
Version	master

Problem/Motivation

The Xero API throws precise error responses in various cases.

At the moment these are all turned into a simple Guzzle RequestException. Which doesn't make it easy to catch specific errors or provide helpful log messages.

Proposed Resolution

We should have a family of XeroExceptions, extending RequestException, that XeroClient returns in various cases.

Additional Information

So far I'm imagining this hierarchy:

• XeroClientException extends RequestException
• XeroAuthException extends XeroClientException and indicates an auth failure like the ones we currently provide custom messages for.
• XeroRateLimitException extends XeroClientException and indicates a 429 response with details like when to retry
• XeroApiException extends XeroClientException and indicates a 400 response of the kind that Xero gives ApiException as the root XML node for.
• XeroValidationException extends XeroApiException and indicates an ApiException xml where "type" is ValidationException. Example below. It can have an array of validation errors.
• XeroQueryParseException extends XeroApiException and indicates an ApiException xml where "type" is QueryParseException. Example below. It has a simple string message.

Official documentation is here:
https://developer.xero.com/documentation/api/http-response-codes

Also relevant is:
https://github.com/calcinai/xero-php#thrown-exceptions

<ApiException xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <ErrorNumber>10</ErrorNumber>
  <Type>ValidationException</Type>
  <Message>A validation exception occurred</Message>
  <Elements>
    <DataContractBase xsi:type="Contact">
      <ValidationErrors>
        <ValidationError>
          <Message>The contact name John Smith is already assigned to another contact. The contact name must be unique across all active contacts.</Message>
        </ValidationError>
      </ValidationErrors>
      <ContactID>52ef39ba-e10d-46da-8e41-42675bec0207</ContactID>
      <ContactNumber>1484</ContactNumber>
      <ContactStatus>ACTIVE</ContactStatus>
      <Name>John Smith</Name>

<ApiException xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <ErrorNumber>10</ErrorNumber>
  <Type>ValidationException</Type>
  <Message>A validation exception occurred</Message>
  <Elements>
    <DataContractBase xsi:type="Invoice">
      <ValidationErrors>
        <ValidationError>
          <Message>Account code '4060' is not a valid code for this document.</Message>
        </ValidationError>
      </ValidationErrors>
      <Contact>
        <ContactID>0dd1ad70-d9fb-9b7c-f98b-571fbb0103c4</ContactID>
        <ContactNumber>2211</ContactNumber>
        <Name>nchBgG70</Name>

<ApiException xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <ErrorNumber>16</ErrorNumber>
  <Type>QueryParseException</Type>
  <Message>Operator '==' incompatible with operand types 'Guid' and 'String'</Message>
</ApiException>