Developer Docs•stable•Updated 2026-07-06

Errors

Handle Kadryn authentication, validation, policy, provider, rate limit and server errors safely.

Kadryn errors should be handled by class.

Do not treat every non-2xx response as retryable.

Some failures require a retry. Others require configuration, metadata, permissions or policy changes.

Error classes

| Class | Retry? | Typical fix | | --- | --- | --- | | Authentication | No | Fix or rotate the Kadryn API key. | | Authorization | No | Check role, plan and workspace access. | | Validation | No | Fix payload, headers or metadata. | | Policy block | No | Inspect Guardrails decision and update config if needed. | | Provider key | No | Add, fix or rotate provider key. | | Provider error | Sometimes | Follow provider-specific guidance. | | Rate limit | Yes | Backoff and preserve idempotency. | | Timeout | Yes | Retry safely with idempotency. | | Server error | Yes | Retry with bounded backoff. |

Authentication errors

Common causes:

  • missing Authorization header;
  • invalid API key;
  • provider key used instead of Kadryn API key;
  • key belongs to another workspace;
  • key was rotated but service was not redeployed.

Fix authentication before retrying.

Validation errors

Validation errors mean the request shape is wrong.

Common causes:

  • missing Content-Type: application/json;
  • invalid JSON;
  • invalid timestamp;
  • numeric cost sent as a float instead of cents string;
  • unsupported provider or model field;
  • missing metadata required by policy.

Do not retry unchanged validation errors.

Policy blocks

A policy block means Kadryn received the request, but governance denied it.

Common causes:

  • budget cap reached;
  • model not allowed;
  • production metadata missing;
  • approval required;
  • environment restriction;
  • plan entitlement restriction.

Open Logs & Traces and inspect the decision.

Rate limits

Rate limits may be enforced by Kadryn or by the upstream provider.

Use:

  • exponential backoff;
  • jitter;
  • bounded retries;
  • idempotency keys;
  • queue-based retry for workers.

Error logging

Log enough to debug without leaking secrets.

Safe fields:

  • status code;
  • error code;
  • Kadryn request ID;
  • trace ID;
  • request group ID;
  • project;
  • environment;
  • provider;
  • model.

Unsafe fields:

  • Authorization header;
  • Kadryn API key;
  • provider key;
  • raw secret metadata;
  • sensitive prompt content.

Troubleshooting workflow

  1. Identify the status code and error code.
  2. Search by request ID or trace ID in Logs & Traces.
  3. Check Diagnostics for setup-level issues.
  4. Check provider key readiness if Gateway failed.
  5. Check policy decisions if the request was blocked.
  6. Retry only if the error is transient.

Related pages