Request lifecycle

Before an operation runs, SellApp checks who you are, which store you selected, what your key and account can do, and whether the request is valid. It also applies rate limits and checks that the resource belongs to your store.

Bearer key → X-STORE → abilities → rate limit → validation → operation → response

Keep the request ID

Every response includes a server-generated X-Request-ID. Error responses also include the same value in request_id. Log it with the HTTP method, path, status, duration, idempotency key, and your own business identifier. Do not log the bearer key, webhook signing secret, payout destination, or sensitive deliverables.

The request ID identifies one HTTP attempt. Retrying creates a new request ID. An idempotency key has a different job: it identifies one intended change, such as a payout, across all its retry attempts. Keep that key the same.

Decide whether to retry

• Retry GET requests after network failures, 429, and transient 5xx responses.
• Retry writes only when the operation is inherently idempotent or you supplied a documented idempotency key.
• Never retry an unchanged 400, 401, 403, 404, or 422 response.
• Honor Retry-After on 429; otherwise use exponential backoff with jitter.
• Set a maximum number of attempts or a time limit for the whole operation.

If the connection fails after sending a non-idempotent write, read the related resource or search by your business identifier before sending it again. A lost response does not mean the change failed: the server may have finished it.

Continue with Errors and retries, Idempotency, and Rate limits.