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 noerrors
component. This happens when no error occurred during processing, but one or more warnings occurred. - There is an
errors
component and nowarnings
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
orwarnings
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
, orApplication
) to indicate the type of problem encountered.ErrorParameter
: Has two required fields, both strings, namedname
andvalue
.
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:
Field |
Type |
Description |
---|---|---|
errorData |
object |
The |
errorData.category |
ErrorCategory |
The category type for this error or warning. It takes an
|
errorData.domain |
string |
Name of the domain containing the service or application. |
errorData.errorId |
number |
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. |
errorData.longMessage |
string |
An expanded version of |
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 |
errorData.parameters |
ErrorParameter |
This optional complex field type contains a list of one or more context-specific |
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, |
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:
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.