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

# Troubleshooting & FAQ

> Common problems running agents on Karta, what causes them, and how to fix them - plus where to check status and how to reach us.

Most issues fall into a handful of buckets. Find the symptom below; each points at
the cause and the fix. For the full list of status codes, see the
[errors reference](/api-reference/errors).

<Tip>
  Karta supports platform behavior: deploys, keys, budgets, sessions, and
  dashboard flows. Your application code, prompts, and model outputs remain your
  responsibility; support can help identify which layer is failing.
</Tip>

## Deploys and releases

| Symptom                 | Likely cause                            | Fix                                                                                    |
| ----------------------- | --------------------------------------- | -------------------------------------------------------------------------------------- |
| Build failed            | The release did not build.              | Check build logs in the dashboard or CLI. The previous active release keeps serving.   |
| `409 no active release` | The agent has no active release.        | Deploy again, then confirm the active release. See [Deploy loop](/deploy/deploy-loop). |
| New release misbehaves  | The active pointer is on a bad release. | Roll back to a previous release from the dashboard or CLI. Rollback does not rebuild.  |

## 401 Unauthorized

Your API key is missing, wrong, or revoked.

* Keys are shown **once** at creation and stored as a prefix/last-4 afterward - if
  you lost it, rotate a new one rather than hunting for the old.
* Confirm you are sending it as a `Bearer` token. See
  [Authentication](/api-reference/authentication).
* A revoked or rotated key fails closed immediately.

## 402 Budget exhausted

A budget cap was hit. Karta checks the cap **before** running anything, so you get
a clean 402 instead of a surprise bill.

* Raise or adjust the cap in **Usage & budgets**, or wait for the period to reset.
* Confirm whether the reason is org budget, API-key sub-limit, user cap, karta
  cap, seat cap, anonymous-widget ceiling, or prepaid credits.
* See [Usage, cost & budgets](/platform/usage-and-budgets).

## A model call fails (BYOK)

If you bring your own model key, a model error usually means the key is invalid,
expired, or out of quota with your provider.

* Re-check the key in **BYOK settings**; rotate it if your provider rotated it.
* Without BYOK, model inference is billed through Karta and you will not hit this.
  See [Bring your own key](/platform/byok).

## 404 on a session

Sessions are org- and agent-scoped, default-deny.

* A session created under a different agent (or org) returns 404 by design -
  the caller only sees sessions in its own scope.
* Check you are using a session token scoped to the right agent. See
  [Sessions](/api-reference/sessions) and [Session tokens](/security/session-tokens).

## A webhook endpoint went quiet

| Symptom                       | Likely cause                                                                                  | Fix                                                                                       |
| ----------------------------- | --------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
| Endpoint is disabled          | It crossed the consecutive failure threshold.                                                 | Fix the endpoint, then run `karta webhooks enable <id>` or re-enable it in the dashboard. |
| Signature verification fails  | The verifier used a parsed body instead of the raw request body, or the wrong signing secret. | Verify `Karta-Signature` against the raw body. See [Webhooks](/platform/webhooks).        |
| Deliveries retry then exhaust | The endpoint returns non-2xx or cannot be reached.                                            | Return a 2xx quickly, move slow work to your queue, and inspect recent attempts.          |

## 429 Too Many Requests

You hit a rate limit. Back off and retry with exponential backoff; sustained
limits mean you should batch or spread the load.

## Is it me, or is Karta down?

Check the **[status page](https://status.karta.sh)** for live platform health
and incident updates. For trust, legal, and sub-processor materials, use
[karta.sh/trust](https://karta.sh/trust).

## Still stuck? Report a problem

* **From the dashboard:** use **Report a problem** in the footer - it reaches the
  support team with your org and the page you were on already attached.
* **Email:** `support@karta.sh` for product and account help.
* **Security vulnerability:** follow the [security policy](https://karta.sh/security-policy)
  (coordinated disclosure + safe harbor).
* **Abuse or a leaked key:** [report abuse](https://karta.sh/abuse) - no account
  required.
* **Privacy / data requests:** `privacy@karta.sh`. **Legal / DMCA:** `legal@karta.sh`.