Skip to main content
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

{
  "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

FieldTypeNotes
error.codestringStable machine code. See the full list.
error.messagestringHuman-readable summary. Safe to log; don’t show raw to end users.
error.request_idstringAlways include this when contacting support.
error.details[]arrayZero or more per-issue records — see below.
error.approvalobjectPresent on APPROVAL_REQUIRED errors. See details & fix_patch.

​
A detail record

FieldNotes
pathJSON Pointer into the request body, e.g. $.brief.color.
fieldConvenience: the leaf field name.
severityerror, warning, or info. Only error blocks the request.
messagePer-issue human message.
contextStructured data — expected, actual, rule, max, etc.
fix_patchRFC 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_rectFor 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 for the full decision tree.

​
Status codes you’ll see

HTTPMeaningTypical codes
400Your 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
401Authentication failed.UNAUTHORIZED
402You’re out of credits.INSUFFICIENT_CREDITS
403Authenticated but not allowed.FORBIDDEN
404Resource doesn’t exist.NOT_FOUND, BRAND_NOT_FOUND, TEMPLATE_NOT_FOUND, etc.
409Conflict with current state.CONFLICT, IDEMPOTENCY_CONFLICT, APPROVAL_REQUIRED
429Rate limit hit.RATE_LIMIT_EXCEEDED
500Server bug. Retry with backoff.INTERNAL_ERROR, RENDER_FAILED
501Feature not enabled for your account.NOT_IMPLEMENTED
503Temporary degradation. Retry.SERVICE_UNAVAILABLE