The envelope
{
"error": {
"code": "STYLE_LOCK_VIOLATION",
"message": "Color #FF00FF violates BrandKit lock 'palette.primary'.",
"request_id": "req_2k4j8h9d",
"details": [
{
"path": "$.brief.color",
"field": "color",
"severity": "error",
"message": "Color is locked to '#7C3AED' by your BrandKit.",
"context": {
"expected": "#7C3AED",
"actual": "#FF00FF",
"rule": "palette.primary"
},
"fix_patch": [
{ "op": "replace", "path": "/brief/color", "value": "#7C3AED",
"rationale": "Match locked primary color." }
],
"violation_rect": { "x": 32, "y": 96, "w": 256, "h": 48 }
}
]
}
}
Fields
| Field | Type | Notes |
|---|---|---|
error.code | string | Stable machine code. See the full list. |
error.message | string | Human-readable summary. Safe to log; don’t show raw to end users. |
error.request_id | string | Always include this when contacting support. |
error.details[] | array | Zero or more per-issue records — see below. |
error.approval | object | Present on APPROVAL_REQUIRED errors. See details & fix_patch. |
A detail record
| Field | Notes |
|---|---|
path | JSON Pointer into the request body, e.g. $.brief.color. |
field | Convenience: the leaf field name. |
severity | error, warning, or info. Only error blocks the request. |
message | Per-issue human message. |
context | Structured data — expected, actual, rule, max, etc. |
fix_patch | RFC 6902 JSON Patch operations to apply to your request to fix the issue. Apply at your own risk — it’s a suggestion, not a guarantee. |
violation_rect | For visual errors (e.g., text overflow), the bounding box you can highlight in your UI. |
What to do with errors
4xx with code → do not retry, fix the request
4xx + fix_patch present → apply patch, retry once
429 RATE_LIMIT_EXCEEDED → honor Retry-After, then retry
5xx → exponential backoff, max 5 retries
Status codes you’ll see
| HTTP | Meaning | Typical codes |
|---|---|---|
| 400 | Your request is malformed or violates policy. | INVALID_REQUEST, VALIDATION_FAILED, STYLE_LOCK_VIOLATION, INVALID_IDEMPOTENCY_KEY, API_VERSION_UNSUPPORTED, POLICY_VIOLATION, SELF_ACTION_NOT_ALLOWED |
| 401 | Authentication failed. | UNAUTHORIZED |
| 402 | You’re out of credits. | INSUFFICIENT_CREDITS |
| 403 | Authenticated but not allowed. | FORBIDDEN |
| 404 | Resource doesn’t exist. | NOT_FOUND, BRAND_NOT_FOUND, TEMPLATE_NOT_FOUND, etc. |
| 409 | Conflict with current state. | CONFLICT, IDEMPOTENCY_CONFLICT, APPROVAL_REQUIRED |
| 429 | Rate limit hit. | RATE_LIMIT_EXCEEDED |
| 500 | Server bug. Retry with backoff. | INTERNAL_ERROR, RENDER_FAILED |
| 501 | Feature not enabled for your account. | NOT_IMPLEMENTED |
| 503 | Temporary degradation. Retry. | SERVICE_UNAVAILABLE |