Errors
Error responses use a consistent envelope so integrations can distinguish between auth problems, missing permissions, validation failures, and unexpected runtime errors.
Every error returns code, message, and request_id.
The integration API keeps errors stable and machine-readable. The error.code field is the primary branching key for your integration logic.
{
"error": {
"code": "forbidden",
"message": "Missing required scope: inventory.write."
},
"request_id": "a653120e-7ab4-44c7-af78-e5f10d1862e2"
}Handle auth and validation errors explicitly.
Most integrations should explicitly branch on unauthorized, forbidden, validation_error, and not_found. Internal errors are usually transient or operational and should include request_id in any support escalation.
Retry only when it is safe to do so.
GET requests are naturally safe to retry. For POST requests, send an Idempotency-Key and retry the exact same payload. If the same key is reused with a different payload, the API returns a validation conflict instead of applying ambiguous writes.