Handling errors | eBay Developers Program

If your request encounters problems during processing, the eBay servers can respond with either an error or warning condition. While processing might continue if a warning is encountered, the processing stops when errors are encountered.

API error and warning responses

There are three different types of response components that you can receive after you send a request. Depending on what happens during the request processing, you can receive either errors or warnings, as follows:

There is a warnings component and no errors component. This happens when no error occurred during processing, but one or more warnings occurred.
There is an errors component and no warnings component. This happens when one or more errors occurred during processing. While warnings may also have occurred during processing, they are not included in any response with an error component.
There is neither an errors or warnings component. This happens when no warnings and no errors occurred during processing.

Returned error and warning objects are the same type (ErrorData) and have the same fields.

Note that some ErrorData fields take custom types, as defined here:

ErrorCategory: Takes one of three values (Request, Business, or Application) to indicate the type of problem encountered.
ErrorParameter: Has two required fields, both strings, named name and value.

The following sections show typical responses for each of the three possibilities. The table in the Error and warning response field values section below lists all fields that could be included in a response when either errors or warnings occurred during request processing.

A warning response

The following example shows a warnings response component with no errors component:

 {
    "warnings": [
      {
        "errorId": long,
        "domain": "string",
        "subDomain": "string",
        "category": "ErrorCategory",
        "message": "string", 
        "longMessage": "string",
        "inputRefIds": ["string"],
        "outputRefIds": ["string"],
        "parameters": [ErrorParameter]
      }
    ],
    "resource": "Hello, eBay followers!"
  }

Note that because warnings do not stop processing, the HTTP status code returns as 200.

An error response

Here is an errors response component with no warnings component:

  {
    "errors": [
      {
        "errorId": long,
        "domain": "string",
        "subDomain": "string",
        "category": "ErrorCategory",
        "message": "string", 
        "longMessage": "string",
        "inputRefIds": ["string"],
        "outputRefIds": ["string"],
        "parameters": [ErrorParameter]
      }
    ]
  }

A response without errors or warnings

And finally, here's a response without either an errors or warnings component:

  HTTP/1.1 200 OK

  {
    "resource": "Hello, eBay follower!!"
  }

Error and warning response field values

The following table describes the fields that can be returned in an errors or warnings container:

API error and warning fields
Field	Type	Description
errorData	object	The `errors` or `warnings` object type.
errorData.category	ErrorCategory	The category type for this error or warning. It takes an `ErrorCategory` object which can have one of three values: `APPLICATION`: Indicates an exception or error occurred in the application code or at runtime. Examples include catching an exception in a service's business logic, system failures, or request errors from a dependency. `BUSINESS`: Used when your service or a dependent service refused to continue processing on the resource because of a business rule violation such as "Seller does not ship item to Antarctica" or "Buyer ineligible to purchase an alcoholic item". Business errors are not syntactical input errors. `REQUEST`: Used when there is anything wrong with the request, such as; authentication, syntactical errors, rate limiting or missing headers, bad HTTP header values, and so on.
errorData.domain	string	Name of the domain containing the service or application.
errorData.errorId	number (long)	A positive integer that uniquely identifies the specific error condition that occurred. Your application can use error codes as identifiers in your customized error-handling algorithms.
errorData.inputRefIds	string	Identifies specific request elements associated with the error, if any. `inputRefId`'s response is format specific. For JSON, use JSONPath notation.
errorData.longMessage	string	An expanded version of `message` that should be around 100-200 characters long, but is not required to be such.
errorData.message	string	An end user and app developer friendly device agnostic message. It explains what the error or warning is, and how to fix it (in a general sense). Its value is at most 50 characters long. If applicable, the value is localized in the end user's requested locale.
errorData.outputRefIds	string	Identifies specific response elements associated with the error, if any. Path format is the same as `inputRefId`.
errorData.parameters	ErrorParameter	This optional complex field type contains a list of one or more context-specific `ErrorParameter` objects, with each item in the list entry being a parameter (or input field name) that caused an error condition. Each `ErrorPrameter` objects consist of two fields, a `name` and a `value`.
errorData.parameters.name	string	This is the name of the parameter/field for which the error was thrown.
errorData.parameters.value	string	This is the value of the parameter/field for which the error was thrown.
errorData.subDomain	string	Name of the domain’s subsystem or subdivision. For example, `checkout` is a subdomain in the `buying` domain.

An example error response

The following error shows a sample response if there is a problem with one of the parameters passed into the call:

 {
  "errors": [
    {
      "errorId": 15008,
      "domain": "API_ORDER",
      "category": "REQUEST",
      "message": "Invalid Field : itemId.",
      "inputRefIds": [
        "$.lineItemInputs[0].itemId"
      ],
      "parameters": [
        {
          "name": "itemId",
          "value": "2200077988|0"
        }
      ]
    }
  ]
}

Common errors

When you make a call to an eBay API, you can get a response that contains errors or warnings as described above. However, each API can also return common errors, which are error conditions that can occur while processing a call to any API. Common errors stop processing and they must be addressed before you can get a successful response from your call.

The common errors use the same error response structure that the individual interfaces use:

  {
    "errors": [
      {
        "errorId": long,
        "domain": "string",
        "subDomain": "string",
        "category": "ErrorCategory",
        "message": "string", 
        "longMessage": "string",
        "inputRefIds": ["string"],
        "outputRefIds": ["string"],
        "parameters": [ErrorParameter]
      }
    ]
  }

Below is a list of the most frequently encountered common errors:

Common error messages
Error ID	Error Category	Message	Long Message	Domain	HTTP Status Code
1001	REQUEST	Invalid access token	Invalid access token. Check the value of the Authorization HTTP request header.	OAuth	401
1002	REQUEST	Missing access token	Access token is missing in the Authorization HTTP request header.	OAuth	400
1003	REQUEST	"Token type in the Authorization header is invalid:" + scheme	"Token type in the Authorization header is invalid:" plus scheme	OAuth	400
1004	REQUEST	Internal error	Error process the access token.	OAuth	500
1100	REQUEST	Access denied	Insufficient permissions to fulfill the request.	OAuth	403
2001	REQUEST	Too many requests	The request limit has been reached for the resource.	ACCESS	429
2002	REQUEST	Resource not resolved	A resource (URI) associated with the request could not be resolved.	ACCESS	404
2003	APPLICATION	Internal error	There was a problem with an eBay internal system or process. Contact eBay developer support for assistance.	ACCESS	500
2004	REQUEST	Invalid request	Request has errors. For help, see the documentation for this API.	ACCESS	400
3001	REQUEST	Request rejected		ROUTING	400
3002	REQUEST	Malformed request	The request has errors. For help, see the documentation for this API.	ROUTING	400
3003	REQUEST	Resource not found	A resource (URI) associated with the request could not be resolved.	ROUTING	404
3004	APPLICATION	Internal error		ROUTING	500
3005	APPLICATION	Internal error		ROUTING	502

Note: For details on HTTP status codes, see Response components.