All eBay REST operations respond in a standard manner.

Interpreting the response

When you successfully put together and send an eBay REST request, the eBay servers respond with the following:

  • An HTTP status code
  • The response payload (if applicable)
  • HTTP response headers

If by chance your request does not succeed, all eBay REST APIs share a common error structure, which makes handling errors across APIs easier than ever. For details on the REST error message structure, see Handling error messages.

HTTP status codes

Each response from a request to an eBay REST operation contains an HTTP status code that relays the status of your request. HTTP status codes are defined by W3C RFC 2616, section 10. The high-level codes are defined as follows:

HTTP status code
High-level HTTP Status Code Description
1xx Informational—Codes returned in the 100 range denote the response contains informational data, such as a switching protocol message.
2xx Success—Codes returned in 200 range indicate the request was successfully received, understood, and accepted. While a code of 200 indicates OK, other 200 codes can indicate other types of success.
  200 OK—The request succeeded. The information returned with the response is dependent on the method used in the request.
  201 Created—The request was fulfilled and a new resource was created. The newly created resource can be referenced by the URI(s) returned Location header field.
  202 Accepted—The request has been accepted for processing, but the processing has not been completed.
  204 No Content—The server fulfilled the request, but does not need to return an entity-body (payload).
3xx Redirection—Codes returned in the 300 range indicate your request was redirected.
4xx Client Error—Codes returned in the 400 range denotes that some sort of client error was encountered. Please check the error code for more information on the type of error encountered.i
5xx Server Error—Codes returned in the 500 range denote an error occurred on the server side. Refer to the specific error for details.

See RFC 2616, Section 10 for more details.

The response payload

Like the request payloads, all successful responses from a call to an eBay REST operation contain payloads formatted in JSON (where applicable).

The following code example shows a response payload from a call to GET https://api.sandbox.ebay.com/buy/v1/deals, which contain a list of the current eBay Deals items for a specified category:

{
  "deals": [
    {
      "groupId": "v1|110007544646|0",
      "title": {
        "content": "Apple iPhone 4S - 32GB - White Smartphone-14485"
      },
      "imageLink": "http://i.ebayimg.ebay.com/00OmEU/$_35.JPG",
      "minPrice": {
        "value": 300,
        "currency": "USD"
      },
      "maxPrice": {
        "value": 300,
        "currency": "USD"
      },
      "categoryIdentifier": "Cell Phones & Smartphones",
      "quantitySold": 12,
      "discount": true,
      "originalPrice": {
        "value": 401,
        "currency": "USD"
      },
      "quantityLimitPerBuyer": 5,
      "priceDisplayCondition": "ALWAYS_SHOW",
      "itemGroup": "/buy/v1/item_group/v1|110007544646|0",
      "dealEndtime": {
        "value": "2015-11-27T14:59:00.000Z",
        "formattedValue": "2015-11-27T14:59:00.000Z"
      }
    },
    {
      "groupId": "v1|170008030026|0",
      "title": {
        "content": "Packing and Shipping boxes - 19273-1445985364525"
      },
      ...
      }
    }
  ]
}

HTTP response headers

The response from each call to an eBay REST operation contains a set of HTTP headers. The headers returned by each operation are unique to the specific operation, although most operations do return the HTTP headers described in the following table.

Note: All headers should be treated as case-insensitive and must follow RFC standards.

Common HTTP response headers
HTTP response header Description
Content-type

Describes character set and/or MIME type of the response, which should be the same as the values specified in the Accept-Charset and Accept-Encoding request headers, respectively.

If the server cannot return the result specified in either of those request headers, the server usually ignores those values and returns the result in the value(s) specified by Content-Type, without returning an error code.

Note that there can be multiple Content-Type response headers, with one identifying the character set and another the MIME encoding.

Examples:

Content-Type: application/json; charset=utf-8

Content-Type: application/jsonl

Content-Type: charset=utf-8

Content-Language

Describes the natural language of the response. This should be the language specified in the Accept-Language request header. However, if the server cannot return the result in the value specified by Accept-Language, the server usually ignores Accept-Language, and returns a value that is either a language code or a language code with a country option (for example, en-US for United States English as opposed to British English). See Marketplace ID and language header values for the values supported by eBay.

Example: Accept-Language: en-US
Location When creating a new resource with a POST call, eBay does not return a response with a payload. Instead, the response contains a Location header that contains a URI to the newly-created resource. Parse the URI to get the ID of the resource, or you can use the URI in a GET request to retrieve the ID of the resource.
Warning Carries additional information about the status or transformation of a message that might not be reflected in the status code.

Refer to the documentation on each REST operation for the specifics of the HTTP headers that can be returned by that call.

Note: The eBay calls return multiple response headers. When contacting DTS for support, please be sure to track the response headers from the calls for which you have questions; they help the support staff determine the specifics of call(s) you are referencing.

Error messages

All eBay REST operations use the same error message format, which greatly simplifies your error-handling routines—you can parse all error messages using the same code. For more, see Handling error messages.