# Exclusive Stickers public API versioning and deprecation policy

Effective date: 2026-10-25. Scope: the public generateProductFeed, generateSitemap and agentResources handlers only. This policy does not cover internal platform APIs, private orders, payments or administration.

## Version 1

Handler responses identify the contract with the API-Version: 1 response header. The existing catalog and sitemap URLs retain their current request and successful response formats. The agentResources endpoint accepts the API-Version: 1 request header or version=1 query parameter; unsupported or conflicting versions return HTTP 400 and a structured JSON error. The OpenAPI ApiVersion header parameter documents this negotiation. Catalog and sitemap retain their existing response-header versioning; they do not negotiate a request header. OpenAPI info.version is the documentation version, not a different API version.

Within version 1, existing documented fields, meanings and successful formats remain compatible. New optional fields may be added; clients should ignore unknown fields. Breaking changes require a new major version and a migration guide rather than silently replacing version 1.

## Deprecation and sunset

Before a planned retirement, publish a migration notice here and in /docs at least 90 calendar days before shutdown. Keep the old version available during that period. A deprecated endpoint will send Deprecation as an RFC 9745 Structured Field date (an @ prefix followed by Unix seconds), Sunset as an RFC 8594 HTTP-date, and a Link with rel="deprecation" to the migration notice. Sunset must be later than the deprecation date. No endpoint is currently deprecated, so these headers are intentionally absent. Critical security or legal requirements may require an expedited change, documented as soon as possible.

## Rate limits and retry behaviour

There is no application-managed public quota yet. The hosting service may impose its own limits before a handler runs. The app does not fabricate remaining-request counters or promise that every platform error is JSON. If a 429 includes Retry-After, honor its delay-seconds or HTTP-date value. Otherwise use capped exponential backoff with jitter, stop after repeated failures, and contact support through the contact page. Cache catalog responses for the advertised five minutes and sitemap/discovery responses for the advertised hour.

Standard rate-limit response headers require a real shared enforcement mechanism and an approved quota; they are not currently emitted by these handlers.