Errors

Status codes

Status	Body	Meaning	What to do
400	{"error": "…"} or a validation problem	The request is malformed or breaks a documented limit.	Fix the request. Do not retry unchanged.
401	(empty)	Token missing, unknown, expired or revoked; installation removed; app suspended; or the store is not active.	Get a new token once. If that fails too, stop and alert — the installation is gone or disabled.
403	(empty)	Your installation lacks the scope this operation requires.	Ask the merchant to grant it. The operation’s reference page names the scope.
404	varies	The record does not exist in this store. A record belonging to another store is always 404, never 403.	—
409	{"error": "…"}	An idempotent request with this key is still running.	Wait Retry-After and retry with the same key.
422	{"error": "…"}	This Idempotency-Key was already used with a different request.	Use a new key for a new request.
429	{"error": "…"}	Rate limit exceeded.	Wait Retry-After seconds.
5xx	problem details	A platform fault. Internals are never included.	Retry with backoff; idempotent writes are safe to retry.

Partial success is normal for batch routes

Batch routes — bulk product updates and media imports — answer 200 when the request was valid, and report each row separately. A 200 with failed: 3 means three rows did not apply. Always read the per-row status.

Bodies you should not parse

401 and 403 currently have empty bodies. The platform knows the reason (for example tenant_not_active) but does not yet return it. Handle these by status code alone. See limitations.