Errors
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.