> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kynva.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Error overview

> One envelope, predictable codes, machine-readable details. Built for automatic recovery.

Every Kynva error — regardless of status code — uses the **same response envelope**. Your error handler only ever has to look in one place.

## The envelope

```json theme={null}
{
  "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](/errors/codes).                                          |
| `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](mailto:support@kynva.ai).                           |
| `error.details[]`  | array  | Zero or more per-issue records — see below.                                                       |
| `error.approval`   | object | Present on `APPROVAL_REQUIRED` errors. See [details & fix\_patch](/errors/details-and-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
```

See [Troubleshooting](/errors/troubleshooting) for the full decision tree.

## 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`                                                                                                                                               |