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 API answered the request directly (authentication, rate-limit and cache decisions) instead of passing it through to the platform.

Code	HTTP	Meaning
unauthorized	401	Missing/invalid Authorization header
forbidden	403	Authenticated but lacks scope, pilot enrollment, or an active Enterprise plan (the API is Enterprise-only)
not_found	404	Resource doesn't exist or doesn't belong to your store
bad_request	400	Validation error; see message
method_not_allowed	405	Path exists for another method
rate_limited	429	Per-minute limit; Retry-After header included
too_many_concurrent	429	Too many expensive calls in flight (images, AI generate); 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

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

On https://api.dzbuild.app, a 4xx returned for a write is cached against your Idempotency-Key for 24 hours: retrying with the same key replays that same error, flagged with Idempotency-Replay: 1, without re-running anything. Fix the request and send it with a new key. Errors returned before the request is processed — 401, 403, 429, or a 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.