Update error handling documentation.

[nrathi]

I upgraded to 9.1.1 for an auth token fix, but saw that errors are handled differently now. I read through the documentation but it's not matching what I'm seeing in practice (for the Trading API).

The docs say:

try {
  const result = await eBay.trading.GetItem({
    ItemID: 'itemId',
  });
  console.log(result);
} catch (error) {
  ...
  // in error there is also the field "meta" with the response
  if (error instanceof EBayApiError && error.meta?.res?.status === 404) {
    // not found
    
    // The first error
    console.log(error?.firstError);
  }
}

In practice, what I'm seeing is:

If there are no errors with SeverityCode "Error" (as opposed to "Warning")
=> Then error.meta is EBayTraditionalErrorResponse & ExpectedResponseType

If there is an error with SeverityCode "Error"
=> Then error.meta is EBayTraditionalErrorResponse

Furthermore, I am not seeing res as a field on error.meta

So for example, if you call api.trading.UploadSiteHostedPictures with an expected response type of IUploadPictureResponse and the pictures aren't high quality (warning, not error)
Then the function will throw, and error.Errors will have the relevant warning
And error.meta will be of the type EBayTraditionalErrorResponse & ExpectedResponseType

Here's an example response:

Timestamp: '2024-12-19T04:57:03.299Z',
Ack: 'Warning',
Errors: {
  ShortMessage: 'Quality value of the JPEG format picture you uploaded is lower than recommended.',
  LongMessage: 'To reduce possible issues with picture display quality, eBay recommends that pictures you upload have a JPEG quality value of 90 or greater.',
  ErrorCode: 21916791,
  SeverityCode: 'Warning',
  ErrorParameters: { Value: 90, ParamID: 0 },
  ErrorClassification: 'RequestError'
},
Version: 0,
Build: 'mediasvcs-5.0.34_20241119152902605',
PictureSystemVersion: 2,
SiteHostedPictureDetails: {
  PictureSet: 'Standard',
  PictureFormat: 'JPG',
  FullURL: 'https://i.ebayimg.com/00/s/MTAwMFgxMDAw/z/lWkAAOSw6eZnY6ef/$_1.JPG?set_id=2',
  BaseURL: 'https://i.ebayimg.com/00/s/MTAwMFgxMDAw/z/lWkAAOSw6eZnY6ef/$_',
  PictureSetMember: {
    MemberURL: 'https://i.ebayimg.com/00/s/MTAwMFgxMDAw/z/lWkAAOSw6eZnY6ef/$_1.JPG',
    PictureHeight: 400,
    PictureWidth: 400
  },
  UseByDate: '2025-01-18T04:57:03.169Z'
},
req: {...},
// There is no res

Hopefully that makes sense.

[dantio]

@nrathi
Thank you for reporting.
The warning should not be handled as an Error. I'll have a look on this issue.

[nrathi]

Ah, thanks, that makes a lot more sense. I didn't understand why UploadSiteHostedPictures was throwing an error all of a sudden, especially when the "error" was just a warning.

It looks like this is happening for addFixedPriceItem, too, so I'll assume it's happening across the board and add a temporary wrapper around all the endpoints ignoring only-warnings.

async function wrapTradingApiCall<T>(apiCall: () => Promise<T>): Promise<T> {
  try {
    return await apiCall();
  } catch (e) {
    if (e instanceof EBayError && isTraditionalErrorResponse(e.meta)) {
      const errors = convertToArray(e.meta.Errors);
      // If all errors are warnings, return the successful response from meta
      if (errors.every((error) => error.SeverityCode === "Warning")) {
        const response = e.meta as unknown as T;
        if (response != null) {
          return response;
        }
      }
    }
    throw e;
  }
}

[nrathi]

Do you just need to update this function:

ebay-api/src/errors/index.ts

Line 389 in e940786

export const checkEBayTraditionalResponse = (apiResponse: any, data: any) => {

To check if all the "errors" are actually warnings?

[dantio]

Yes, it's the function. I'll git blame and check why the warning is treated as error. I think it was a feature request...

[nrathi]

Is it the "firstError" feature request?

Would you be open to creating a new 8.x.x release with the auth token fix? I am nervous about adding this wrapper to my entire integration.

[dantio]

I would rather fix the "Warning" as "Error" treatment. I'll do an indeep investigation and testing and come back to you.

[nrathi]

Sounds good, keep me posted. In the worst case, can you confirm this looks safe to wrap all my calls with?

async function wrapTradingApiCall<T>(apiCall: () => Promise<T>): Promise<T> {
  try {
    return await apiCall();
  } catch (e) {
    if (e instanceof EBayError && isTraditionalErrorResponse(e.meta)) {
      const errors = convertToArray(e.meta.Errors);
      // If all errors are warnings, return the successful response from meta
      if (errors.every((error) => error.SeverityCode === "Warning")) {
        const response = e.meta as unknown as T;
        if (response != null) {
          return response;
        }
      }
    }
    throw e;
  }
}```

[nrathi]

Hey, any update? Sorry to be a pain. Just started hitting this auth issue as I mentioned, so want to get a fix out ASAP.

[dantio]

Hey Ill have time tomorrow

[dantio]

I dig through the changes and the check for the "Failure" was mistakenly removed.
I have added the check back:

ebay-api/src/errors/index.ts

Line 401 in a1e939a

if ('Errors' in data && data.Ack !== 'Failure') {

RC

[dantio]

@nrathi
Have you already tried the RC version?

[nrathi]

Yes, I took the update as soon as it came out! No issues on my end.