Handling errors

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.

There are two types of errors and warnings:

  • API errors and warnings
  • Common errors

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 HTTP status codes.