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.