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

ClassRetry?Typical fix
AuthenticationNoFix or rotate the Kadryn API key.
AuthorizationNoCheck role, plan and workspace access.
ValidationNoFix payload, headers or metadata.
Policy blockNoInspect Guardrails decision and update config if needed.
Provider keyNoAdd, fix or rotate provider key.
Provider errorSometimesFollow provider-specific guidance.
Rate limitYesBackoff and preserve idempotency.
TimeoutYesRetry safely with idempotency.
Server errorYesRetry 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