Errors and versioning

Read the error before deciding to retry

The draft uses a consistent error envelope containing a code, message, and request identifier. Some errors include a retry interval. Keep the request ID when asking for help; never send your API key.

Operation reference pages show the exact error schemas and synthetic examples. A failed HTTP request is different from a successful price batch containing an item with status: missing.

Proposed status codes

• 400: malformed input, unknown or repeated query parameters, invalid identifiers, or an invalid/expired cursor. Correct the request before retrying.
• 401: missing, invalid, or revoked key. Check the key configuration.
• 403: the key lacks the required scope. Check its permissions.
• 404: a product or route was not found. Do not assume a renamed product can be identified from its title.
• 409: an idempotency key was reused with a different batch. Restore the original body or start a genuinely new job with a new key.
• 413: the request is too large. Use the documented body and batch limits.
• 415: an unsupported content type. Send JSON for the batch operation.
• 429: a rate or quota limit was reached. Inspect the error code and Retry-After before retrying.
• 500: an unexpected service error. Preserve the request ID and avoid tight retry loops.
• 503: the service is temporarily unavailable. Use bounded retries and retain the last successful observation with its original timestamp.

Preview changes

This documentation is versioned as a preview. Request shapes, response fields, limits, and pricing can change before launch. There is no live production contract or deprecation commitment yet.

The intended production convention is a major version in the path, such as /v1. A future breaking change would require an explicit versioning and migration policy. Additive response fields should not break a consumer that ignores fields it does not use.

Preview revision

September 6, 2026 — 0.2.0-preview. Expanded the proposal to Pokémon and One Piece card prices alongside sealed products. Catalog records distinguish cards and sealed products. Batch requests now use items with explicit card variant/condition selections; results echo selection. This replaces the sealed-only 0.1.0-preview draft’s product_ids request and product_id result. All four operation paths remain the same. Synthetic examples only; no API access.

If a behavior would make your integration unreliable, tell us about the failure case before building against this proposal.