Errors, pagination, and idempotency

Error format

API errors use a common JSON shape:

{
  "error": "bad_request",
  "message": "Description of the validation failure"
}

Treat error as the machine-readable code. message is intended for diagnostics and may become more specific without a version change.

Common status codes:

Status	Meaning
400	Malformed input or failed validation
401	Missing or invalid credentials
402	Saved payment method could not complete the purchase
403	Missing scope, disallowed source IP, or collector prerequisite not enabled
404	Resource not found or not visible to this collector
409	Current-state conflict or external-ID idempotency conflict
429	API-key rate limit exceeded
500	Mascot could not complete the request

429 responses include Retry-After in seconds. For transient 500 and network failures, use exponential backoff with jitter and preserve the same external ID on idempotent write operations.

Numbered-page pagination

Items, feed tasks, purchases, offers, sales, eligible sales, shipping batches, and webhook endpoints use one-based page and page_size parameters. The default page size is generally 50 and the maximum is 200 unless an endpoint documents a smaller maximum.

Numbered-page responses include either a pagination object or equivalent top-level page fields. Use total_pages only as a snapshot; records can change between requests.

Cursor pagination

Product discovery uses an opaque cursor so new products do not reorder an in-progress traversal. Do not parse or modify a cursor. Reuse the same filters and sort settings when requesting the next page. A cursor submitted with different filters returns 400.

External IDs and idempotency

External IDs have different scopes and purposes:

Resource	Behavior
Item	Stable integration mapping; unique among non-deleted items for an API key and collector
Purchase	Idempotency key for one product purchase by an API key
Offer creation	Idempotency key for one product and buyer amount by an API key
Offer action	Idempotency key for one accept or reject action by an API key
Shipping batch	Idempotency key for the normalized batch request by an API key and collector

For purchase, offer, and shipping writes:

• Retry an uncertain request with the same external ID and exactly the same semantic input.
• Generate a new external ID for a genuinely new operation.
• Reusing an existing ID for different input returns 409 idempotency_conflict or 409 conflict.

Item feeds do not currently accept a feed-level external ID. Store the returned feed_id before polling the feed.