Application-level errors occur due to problems with business-level data on the client side or on the server side. Application-level errors may occur for a number of reasons, including:

  • The request contains an invalid combination of fields (e.g., a reserve price for a fixed-price listing).
  • The request is missing a required field.
  • The request is valid, but a problem occurred in eBay's internal business logic while processing the data.

Use the following guidelines for handling an application-level error:

  • Symptoms

    An API call request returns an error result set.

  • Verify and retry

    Confirm the input arguments and request are valid, and then resubmit the request.

  • Actions

    • Review the call input to confirm that the input fields and overall format of the request are valid.
    • Refer to API Status to determine if there is a known issue with the API.
    • Contact Support

Parameters

When an application-level error occurs with the Trading API, an Errors container is returned which provides information about the error including:

  • ErrorCode

    The unique code that identifies the specific error condition that has occurred.

  • ShortMessage and LongMessage

    Text descriptions of the condition that has occurred.

  • ErrorParameters

    A container that stores the following information for each request field — if any — that has been identified as being a cause of the problem:

    • ParamID

      Numeric index of the parameter in the list (e.g., 0 for the first parameter, 1 for the second parameter, etc.)

    • ValueThe value/name of the parameter.

  • SeverityCode

    Indicates if the reported issue is an error or a warning:

    • Error

      Typically indicates that a request has failed.

      When this happens, normally only the Errors container and standard output data are returned. No call-specific output fields are returned.

    • Warning

      Typically indicates that a request has been at least partially successfully, but nevertheless, warning messages should still be reviewed and, if necessary, addressed.

      Warning messages may be generic, informational messages, such as informing users about a change in eBay policies or an upcoming call or feature deprecation.

      A warning message may also indicate that a specific field that had been passed into the request payload has been dropped because it is no longer supported or applicable.

The following code samples illustrate:

  • A GetBestOffers request in which the user passes in one version number in the HTTP header and a different version number in the Version request field.
  • The response in which both an error and a warning are included in the Errors container.

Note: Some data in the request and response samples have been masked for privacy reasons.

Request 

<?xml version="1.0" encoding="utf-8"?>
<GetBestOffersRequest xmlns="urn:ebay:apis:eBLBaseComponents">
  <Version>1169</Version>
  <ItemID>2**********0</ItemID>
  <RequesterCredentials>
    <eBayAuthToken>ABC...123</eBayAuthToken>
  </RequesterCredentials>
</GetBestOffersRequest>

Response 

<?xml version="1.0" encoding="utf-8"?>
<GetBestOffersResponse xmlns="urn:ebay:apis:eBLBaseComponents">
  <Timestamp>2020-08-31T02:34:59.381Z</Timestamp>
  <Ack>Failure</Ack>
  <Errors>
    <ShortMessage>Header version 1045 does not match
    request version 1169.</ShortMessage>
    <LongMessage>The version 1045 in the HTTP header X-EBAY-API-COMPATIBILITY-LEVEL
      does not match the version 1169 in the request.
      The HTTP header version will be used.</LongMessage>
    <ErrorCode>21926</ErrorCode>
    <SeverityCode>Warning</SeverityCode>
    <ErrorParameters ParamID="0">
      <Value>1045</Value>
    </ErrorParameters>
    <ErrorParameters ParamID="1">
      <Value>1169</Value>
    </ErrorParameters>
    <ErrorClassification>RequestError</ErrorClassification>
  </Errors>
  <Errors>
    <ShortMessage>Item not found.</ShortMessage>
    <LongMessage>Item "2**********0" is invalid, not activated,
      or no longer in our database.</LongMessage>
    <ErrorCode>21549</ErrorCode>
    <SeverityCode>Error</SeverityCode>
    <ErrorParameters ParamID="0">
      <Value>2**********0</Value>
    </ErrorParameters>
    <ErrorClassification>RequestError</ErrorClassification>
  </Errors>
  <Version>1045</Version>
  <Build>e1045_core_Bundled_3001562_R1</Build>
</GetBestOffersResponse>

The following error and warning information is included in the response payload:

  • The errors container for the warning returns the two version numbers, 1045 and 1169, in separate ErrorParameters containers identified by ParamID=0 and ParamID=1, respectively.
  • The 21549 error code was triggered because eBay could not find any Best Offers associated with the specified Item ID, and due to this fact, no details about a Best Offer for this listing exist.

Variables

Some application-level error messages return additional variables that contain specific information about the error context. Due to the fact that they are variables, the error message text in the Errors by Number uses the following convention when discussing these variables: "replaceable_value". So, whenever you see this text, realize that it is a variable that is going to vary based on the context of the API call. For example:

  • Error message in documentation:

    Invalid CurrencyID "replaceable_value" for selected User "replaceable_value".

  • Error message in actual error:

    Invalid CurrencyID GBP for selected User currencyChallengedeBayUser.

SDK considerations

When using the Trading API SDK for Java or the Trading API SDK for .NET, note that the SDK translates these SOAP application-level errors into ApiException objects. These are returned in the response object for an API call. Applications access exception objects for a particular call through the ApiException property of the concrete API call class that was used when the error(s) occurred (such as AddItemCall.ApiException if the errors occur when listing a new item). Concrete API call classes "inherit" the apiException property from the ApiCall class. At run-time, an application can use the hasError( ) and hasWarning( ) methods of the API call object to determine whether an error (or a warning) has occurred as a result of invoking that object's execution method (e.g., the addItem( ) method for an AddItemCall object). If an error (or a warning) is indicated, then the application accesses the exceptions conveyed in the object's ApiException property.

Each ApiException object can convey multiple exceptions. The ApiException object is an array of objects of type ErrorType. For information about properties of an ErrorType object, refer to ErrorType.