Skip to main content

​
Decision tree

Response status?
├── 2xx → success
├── 401 → fix auth, then retry
├── 402 → top up credits or use kyn_test_ key
├── 403 → fix scope or workspace permission, do NOT retry
├── 404 → fix the ID, do NOT retry
├── 409
│   ├── IDEMPOTENCY_CONFLICT → generate fresh key
│   ├── APPROVAL_REQUIRED    → wait for approval, then retry
│   └── CONFLICT             → resolve state conflict (see message)
├── 429 → honor Retry-After, then retry
├── 4xx with fix_patch → apply patch, retry once
├── 4xx other → fix request, do NOT retry blindly
├── 5xx → exponential backoff, up to 5 retries (same Idempotency-Key)

​
Common gotchas

Three things to check:
  1. Whitespace — Bearer kyn_... (two spaces) is invalid.
  2. Wrong environment — kyn_test_ keys can’t be used against live data, and vice versa. Check the prefix.
  3. Rotation grace expired — if you rotated a key, the old one stops working after 24h.
Almost always a font resolution or asset access issue:
  • Did the brief reference a font your BrandKit doesn’t have?
  • Is an asset URL in the brief reachable from the public internet?
  • Are you using a private asset ID that belongs to a different brand?
Inspect the decisions log if available (compile API) or include the request_id when contacting support.
Three usual causes:
  1. A timestamp in the body changed. Even a millisecond difference makes the body hash different.
  2. Field reordering produced different JSON bytes. Use a canonical serializer (JSON.stringify is fine in JS; in Python use json.dumps(..., sort_keys=True)).
  3. You changed the URL (different query param). The cache is keyed on method + URL + body hash.
You may be hitting a per-category limit you didn’t realize you were spending. For example: a polling loop on GET /facade/render-jobs/{id} shares the reads bucket with the rest of your app.
  • Switch to webhooks for completion notifications.
  • Reduce poll frequency.
  • See the X-RateLimit-Category response header to confirm which bucket you hit.
Check status.kynva.ai. Subscribe to incident updates there so you get pinged before the next one.

​
When to contact support

Send support@kynva.ai an email with:
  • The X-Request-Id from the failing response (always in headers, also in error.request_id).
  • The timestamp of the request, with timezone.
  • The request body (redact any PII).
  • The expected vs actual behavior.
We pull logs by request ID. Without it, debugging takes 10× longer.