Errors and limits
Error format
Every error is JSON with the same shape. MCP tools return the same object with isError: true.
{"error": {"code": "invalid_request", "message": "per_page: 1000 is greater than the maximum of 100",
"status": 400, "request_id": "8f3a1c2d9e4b7a60", "details": {"field": "per_page"}}}| Code | HTTP | Meaning |
|---|---|---|
invalid_request | 400 | The input failed validation; `details` says which field and why |
unauthorized | 401 | Sign-in needed: send an OAuth access token or API key (see WWW-Authenticate) |
invalid_token | 401 | The token or key is expired, revoked, unknown or for another site |
insufficient_scope | 403 | Your token is valid but lacks the scope this call needs |
forbidden | 403 | You may not do this to that item (for example, it is not your listing) |
not_found | 404 | No such item on this site |
conflict | 409 | The request conflicts with the item's current state |
idempotency_mismatch | 422 | This Idempotency-Key was used with a different request body |
rate_limited | 429 | Too many requests; wait Retry-After seconds |
quota_exceeded | 429 | Daily quota used up; resets at 00:00 UTC |
api_disabled | 503 | The API is switched off for maintenance; try again later |
server_error | 500 | Something failed on our side; it has been reported |
Rate limits and quotas
Free for everyone within these limits. Responses carry RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset; a 429 carries Retry-After (seconds).
| Limit | Allowance |
|---|---|
| Anonymous requests per IP | 60 per minute |
| Requests per API key or connected app | 120 per minute |
| Requests per API key or connected app | 20000 per day (UTC) |
| Changes (writes) per account | 60 per hour |
| New listing drafts per account | 20 per 24 hours |
| All requests from one IP | 300 per minute |
Pagination
List operations take page (from 1) and per_page (up to 100) and return items, total, has_more and next_page.
Safe retries
Send an Idempotency-Key header (any unique string) with a change. Repeating the request with the same key within 24 hours returns the first result (header Idempotency-Replayed: true) instead of doing the work twice. The same key with a different body is refused with idempotency_mismatch.
Money
Amounts are whole US dollar cents (an integer: divide by 100 for dollars). Prices exclude VAT; quote_order previews VAT for a billing country.