Error envelope:

{ "error": { "code": "...", "message": "...", "retry_after": 12 },
  "meta": { "request_id": "...", "api_version": "v1", "edge": true } }

meta.request_id and meta.api_version are always present. retry_after appears on 429 only. meta.edge is true only when the edge at api.dzbuild.app wrote the answer itself, for example an authentication or rate-limit refusal or a failed key check, instead of passing the platform's answer through unchanged.

Code	HTTP	Meaning
`unauthorized`	401	Missing/invalid Authorization header
`forbidden`	403	Authenticated but lacks scope, pilot enrollment, or an active Enterprise plan (merchant API keys need Enterprise; installed-app tokens work on every plan). An app token also gets it, with `Apps cannot use this endpoint`, on `/v1/keys`, `/v1/webhooks` and `/v1/changes`
`app_uninstalled`	403	App token: the app is no longer installed on this store
`app_suspended`	403	App token: DZBuild suspended or rejected the app
`app_not_approved`	403	App token: the app is in test mode and this store does not belong to its developer
`app_plan_required`	403	App token: the store's plan is below the app's minimum plan; `message` names the plan
`not_found`	404	Resource doesn't exist or doesn't belong to your store
`bad_request`	400	Validation error; see `message`
`idempotency_key_reuse`	422	The `Idempotency-Key` was already used with a different method, path or body; send a new key
`method_not_allowed`	405	Path exists for another method
`payload_too_large`	413	The request body is larger than 1 MB
`rate_limited`	429	Per-minute limit; `Retry-After` header included. App tokens also have a per-install limit of 120 requests per minute, checked before the store's
`too_many_concurrent`	429	Too many expensive calls in flight (images, AI generate, courier calls, home page section writes); retry in a few seconds
`quota_exceeded`	402	Monthly cap hit; upgrade or wait
`server_error`	500	Unexpected server error; safe to retry idempotent calls
`server_error`	502	`api.dzbuild.app` could not check your key with the platform; retry shortly

A details object is reserved for future structured validation output. No endpoint emits it today, so don't branch on it.

Retrying a failed write

A 4xx returned by a write's handler is stored against your Idempotency-Key for 24 hours, on https://api.dzbuild.app and on the dzbuild.com/api/v1 alias alike: retrying with the same key and body replays that same error, flagged with Idempotency-Replay: 1, without re-running anything. Fix the request and send it with a new key; the old key answers 422 idempotency_key_reuse for the changed body. Refusals that happen before the handler runs, for example 401, the pilot, plan and app_* answers with 403, 429, or a missing or malformed Idempotency-Key, are not cached, and neither are 5xx responses, so the same key can be retried safely. See Idempotency.

Always include meta.request_id when contacting support.

Errors

Retrying a failed write