Error Handling

Topics:

Introduction to Error Handling

Error Types

Customizing Your Application's Error Handling Abilities

Compatible Application Check Requirements for Error Handling

Getting Help When You Cannot Identify the Source of an Error

Introduction to Error Handling

As with all applications, your application should implement at least basic error handling. Doing so grants a number of benefits to the application and the application's end-users.

The most prevalent benefit is the graceful recovery of the application from error states. Without even the simplest form of error handling in an application, its execution can be brought to a complete halt by an error returned by eBay.

Another benefit is that the application can display errors that are more meaningful to the end-user, who will likely not know about the errors that could occur.

Also, by incorporating error handling, an application can more easily be localized for use in different languages. If the application's error messages that correspond to the API error messages are stored in something like a string table, then different string tables can readily be substituted for different languages.

When a problem occurs and a request (or a portion of a request) cannot be executed for some reason, the response includes a list of errors instead of the normal business data. If the request is executed successfully but a minor problem was found or a change was made that you might not expect, the response includes the normal business data accompanied by a list of warnings.

It is a good idea to understand the types of errors and warnings that eBay may return so that you can design your application to handle them gracefully. Sometimes, errors may occur due to problems on eBay's side. For example, error 10007 ("Internal error to the application") indicates an error on the eBay server side, not an error in your application. It is important to understand how to determine whether this has occurred, and when to contact eBay for help.

Error Types

The eBay Platform defines two general types of errors:

See Errors by Number for the latest list of all possible error codes and messages that can be returned.

Application-Level Errors

Application-level errors occur due to problems with business-level data on the client side or on the server side. For example, these are just a few situations that could cause application-level errors:

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

When an application-level error occurs, eBay returns an error object (Error) in the response. Application-level errors are returned as normal HTTP 200 responses. Each error includes a unique code (ErrorCode) that identifies the particular error condition that occurred. It also provides messages (ShortMessage and LongMessage) that indicate the cause of the problem. The text of each message also implies whether the error was due to a problem with the request (e.g., a field was invalid) or due to a problem on the server.

Figure: The API Error Model
API Error Model

If you are using the eBay SDK for Java or the eBay SDK for .NET, please 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.

If you are using the eBay SDK for Java or the eBay SDK for .NET, 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 see ErrorType in the Trading API.

An error can have one of two severity levels. The severity level indicates whether the request should be resent or another action needs to be taken in response to the error. For more information, see SeverityCodeType in the Trading API.

Some application-level error messages return additional variables that contain specific information about the error context. For example, a theoretical error might look like this:

Attribute Set Id {0} does not match category you have entered for this request {1}. Please refresh the meta-data.

The variables are identified by error parameter (ErrorParameter) objects. If you are using an SDK, they are returned in the ErrorType.ErrorParameters property in the form of an ErrorParameterType[] list. These are intended to help you distinguish the context of errors more easily when a response contains multiple errors. Applications can also use these parameters to more easily flag fields that users need to correct.

Each error can contain a list of 0 or more parameters. Each one has a parameter ID attribute (ParamID) that specifies the index of the parameter in the list (e.g., 0 for the first parameter, 1 for the second parameter). It also specifies a value (Value), which is the parameter itself (e.g., the attribute set ID).

The following sample, made using the XML API, generated both an error and a warning.

Example: Sample XML call input leading to error and warning
<?xml version="1.0" encoding="utf-8"?>
<GetBestOffersRequest xmlns="urn:ebay:apis:eBLBaseComponents">
  <Version>304</Version>
  <ItemID>123456</ItemID>
  <RequesterCredentials>
    <eBayAuthToken>ABC...123</eBayAuthToken>
  </RequesterCredentials>
</GetBestOffersRequest>
Example: Sample XML call output containing error and warning
<?xml version="1.0" encoding="utf-8"?>
<GetBestOffersResponse xmlns="urn:ebay:apis:eBLBaseComponents">
  <Timestamp>2006-05-31T02:34:59.381Z</Timestamp>
  <Ack>Failure</Ack>
  <Errors>
    <ShortMessage>Header version 445 does not match
    request version 304.</ShortMessage>
    <LongMessage>The version 445 in the HTTP header X-EBAY-API-COMPATIBILITY-LEVEL
      does not match the version 304 in the request.
      The HTTP header version will be used.</LongMessage>
    <ErrorCode>21926</ErrorCode>
    <SeverityCode>Warning</SeverityCode>
    <ErrorParameters ParamID="0">
      <Value>445</Value>
    </ErrorParameters>
    <ErrorParameters ParamID="1">
      <Value>304</Value>
    </ErrorParameters>
    <ErrorClassification>RequestError</ErrorClassification>
  </Errors>
  <Errors>
    <ShortMessage>Item not found.</ShortMessage>
    <LongMessage>Item "123456" is invalid, not activated,
      or no longer in our database.</LongMessage>
    <ErrorCode>21549</ErrorCode>
    <SeverityCode>Error</SeverityCode>
    <ErrorParameters ParamID="0">
      <Value>123456</Value>
    </ErrorParameters>
    <ErrorClassification>RequestError</ErrorClassification>
  </Errors>
  <Version>463</Version>
  <Build>e463_core_Bundled_3001562_R1</Build>
</GetBestOffersResponse>

eBay SDK for Java

https://go.developer.ebay.com/developers/ebay/documentation-tools/sdks/java

Infrastructure Errors

In the SOAP API, an infrastructure error indicates a communication failure on the part of either your application (including your SOAP client) or the eBay servers. This might include such things as passing an invalid token to authenticate the API call's requesting user.

Use the following guidelines to handle an infrastructure error:

When an infrastructure error occurs, eBay returns a SOAP fault that specifies the details of the errors (FaultDetail). Note that in certain cases a SOAP fault generated by the web services framework (AXIS) may be returned without a FaultDetail node included. An example that can trigger such a case is if an integer is specified for the DetailLevel in the request instead of a valid value for that property. SOAP faults are returned as HTTP 500 error responses, in accordance with the SOAP 1.1 standard.

The fault details object includes a unique code (ErrorCode) that identifies the particular error condition that occurred. It also provides a message (DetailedMessage) that indicates the cause of the problem.

If you are using the eBay SDK for Java, this error classification includes AxisFault exceptions.

For the SOAP API, four general types of SOAP faults are used for infrastructure errors.

Table: Infrastructure Error Types
Fault Type Meaning
Client faults These indicate that a problem occurred with the meta-data that your application submitted. These types of faults fall into these categories:
  • Request authentication failures (unsupported verb, the application is not allowed to make this request, etc.)
  • Application authentication failures (invalid certificates, invalid or missing tokens, etc.)
  • User authentication failures (the requesting user is not a registered member, etc.)
  • Malformed requests (the XML is not well-formed, the encoding is not supported, etc.)
Server faults These indicate that a problem occurred within eBay's infrastructure. These are some examples of conditions that result in such faults:
  • The API servers are not available.
  • A database connection error occurred.
VersionMismatch fault These indicate that the SOAP envelope information your application passed is incorrect. Be sure the localname and namespace match the SOAP version we support, which is SOAP 1.1.
MustUnderstand fault These indicate that a problem occurred with the Web services infrastructure. For example, this type of fault may occur when the SOAP processor on the server cannot process a header element that was sent via your SOAP client. If you are using one of a SOAP client (see Supported Client Environments), please report the issue to eBay Developer Support. If you are using a different SOAP client, please see the Release Notes or Known Issues before contacting eBay to discuss the problem.

 

The SDKs translate SOAP infrastructure-level errors (and, in the case of the eBay SDK for Java, AxisFault errors) into ApiException and SdkException objects. Two key properties are the following: the ErrorType property (indicating the type of error) of ApiException and the Message property (containing the text message of the exception) of SdkException.

An infrastructure error can have one of two severity levels. The severity level indicates whether the request should be resent or another action needs to be taken in response to the error.

Table: Infrastructure Error Severity Levels
Severity Level Meaning
Error This means the request was not processed.
  • If a serious infrastructure error occurs due to a problem on the client side, please resolve the problem before attempting to retry the request.
  • If a serious infrastructure error occurs due to a problem on eBay's side, your application can retry the request as-is a reasonable number of times (eBay recommends twice). If the error persists, contact Developer Technical Support. Once the problem has been resolved, your application can re-send the request in its original form.
Please see Compatible Application Check for more information.
Warning This means the request was processed successfully, but something occurred that you should be aware of.
  • If a client-side warning is returned, you do not need to retry the request. However, depending on the cause or nature of the warning, you may want to resolve the problem.
  • If a server-related warning is returned, you do not need to retry the request. However, you may want to contact Developer Support to obtain a long term solution to the problem to prevent it from reoccurring in the future.

 

The following example, which applies to the SOAP API, shows one way to handle infrastructure error message data using C#.

Example: Catching Infrastructure Errors (C#)
System.Xml.XmlNode details = soapex.Detail;

string severity = "";
string longmsg = "";
string errcode = "";
string srtmsg = "";
try
{
   severity = details.SelectSingleNode("/FaultDetail/Severity").InnerText;
   longmsg = details.SelectSingleNode("/FaultDetail/DetailedMessage").InnerText;
   errcode = details.SelectSingleNode("/FaultDetail/ErrorCode").InnerText;
   srtmsg = soapex.Message;
}
catch (System.NullReferenceException)
{
   severity = "Error";
   longmsg = soapex.Message;
   errcode = "0";
   srtmsg = soapex.Code.Name;
}
SeverityCodeType type = SeverityCodeType.Error;
if (severity != "Error")
   type = SeverityCodeType.Warning;
errorType.ErrorCode = errcode;
errorType.SeverityCode = type;
errorType.LongMessage = longmsg;
errorType.ShortMessage = srtmsg;
// Return or print the error data you need

Other Errors in the SDKs

In the case of the SDKs, all other exception types (aside from application-level and infrastructure-level errors) are translated into SdkException objects. Surround critical application operations in a try..catch construct to handle these exceptions. Use the SdkException.getInnerThrowable( ) method to get the exact exception that occurred.

Customizing Your Application's Error Handling Abilities

An application can use any combination of the error properties for its own error handling. For example, an application might have a specialized module for handling error states. When such a state is detected, the error code could be passed to the error-handling module and used in a decision branch construct to take a special action unique to a given error condition.

To return error messages in a language other than English, specify an appropriate value in the ErrorLanguage field of the request.

To check whether you have accidentally misspelled a field name, passed in a field that does not exist, or if you are using deprecated input fields, set WarningLevel to a value of High. We recommend that you only use this for testing and debugging purposes, not in your production application. We have three error messages associated with WarningLevel.

Table: WarningLevel Messages
Error Code Long Error Message Meaning
21927 The element {0} was found in the input SOAP request. This is not a declared element in the schema and will be ignored. This means you have specified an element that we don't recognize. (This could occur if you spell the element name differently than we do, or if you send it in the wrong node.)
219450 The input object "{0}" is deprecated as of schema version {1}. Replacement: "{2}". This means the object is deprecated as of the specified schema version, and we will stop supporting it for all versions in the future.
219451 The input object {0} is no longer supported and will be ignored. This means we no longer support the object for any schema version.

 

See Errors by Number for the latest list of all possible error codes and messages that can be returned.

If you are using the SDKs, errors come from two sources. API errors are raised by eBay (see Application-Level Errors and Infrastructure Errors). Errors also are raised that are Java or .NET application errors, or errors that might occur as a result of attempting to use SDK classes. These errors need to be handled in different ways.

To handle Java or .NET errors, enclose important and volatile operations (such as creating an object and accessing its methods) in a try..catch construct.

If you are using the SDKs, API errors will not trigger an exception that will be captured by a try..catch construct. Rather, the API call object's execution method would be processed normally, but instead of a result set consisting of data there will be an error construct returned (or data and a warning type error construct in the case of warnings). An API error of this sort typically occurs due to bad or invalid data being supplied as input or by a required value not being supplied. For example, if AddItemCall is used to list an item and no starting price is specified, an API error would result.

If you are using the SDKs, determine if there are any API errors or warnings after a call by calling the hasError( ) and the hasWarning( ) methods of the API call class (AddItemCall, GetSellerListCall, etc.). The hasError( ) method returns a value of true if any API exceptions resulted from the call. In this case, get the call object's exception object using the getApiException( ) method and inspect the exceptions it contains to determine what went wrong. If an API exception occurs, the call results in the return of just an error and no data is returned. The hasWarning( ) method returns a value of true if a warning was returned as a result of the call. Visit the ApiException property of the call object to retrieve the warning. When warnings occur, the call will have been processed normally (such as the listing of an item) and the call returns the normal result set. It is just that the normal result set is also accompanied by the warning.

Compatible Application Check Requirements for Error Handling

We offer a general set of guidelines that you should follow to determine what actions to take to correct errors and when to retry a request. Please see Compatible Application Check for these guidelines.

Getting Help When You Cannot Identify the Source of an Error

  • Support
  • Please note that error 10007 ("Internal error to the application") indicates an error on the server side, not an error in your application.

    Copyright © 2005–2016 eBay Inc. All rights reserved. This documentation and the API may only be used in accordance with the eBay Developers Program and API License Agreement.