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

# Error codes

> Reference table of Audity error codes, what triggers them, and how to resolve each one.

All error responses from the Audity API return JSON with a stable `code` field. Always branch on `code` rather than the human-readable `error` string, which may change between releases.

```json theme={null}
{
  "error": "Human-readable description",
  "code": "STABLE_ERROR_CODE"
}
```

## Authentication and authorization

| HTTP | Code                             | Cause                                                                                   | Resolution                                                               |
| ---- | -------------------------------- | --------------------------------------------------------------------------------------- | ------------------------------------------------------------------------ |
| 401  | `PAT_MALFORMED`                  | The `aky_...` token has the wrong length or contains invalid characters.                | Regenerate the token from Settings → API Tokens.                         |
| 401  | *(no code)*                      | A correctly-shaped token that doesn't resolve to an active key.                         | The token was revoked, expired, or never existed. Create a new token.    |
| 403  | `PAT_ROUTE_NOT_ALLOWED`          | Valid token, but the route is not on the agent allowlist.                               | Use the web app for non-agent routes.                                    |
| 403  | `PAT_NOT_SUPPORTED_FOR_ENDPOINT` | A PAT tried to access a Clerk-only endpoint (e.g. PAT management routes).               | PATs cannot manage other PATs. Use the web app.                          |
| 403  | `PAT_SCOPE_INSUFFICIENT`         | Token is valid but missing a required scope. The `error` message lists what is missing. | Regenerate the token with the correct scopes (`read`, `write`, or both). |
| 503  | `PAT_DISABLED`                   | The agent API kill switch is off (`AUDITY_AGENT_API_ENABLED`).                          | Contact [support@auditynow.com](mailto:support@auditynow.com).           |

## Billing and tier

| HTTP | Code             | Cause                                                                         | Resolution                                                                                                                             |
| ---- | ---------------- | ----------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| 402  | *(credit error)* | Insufficient credits for the operation.                                       | Top up credits from the Audity billing page, or upgrade your plan. Check balance with `GET /api/user/credits` before batch operations. |
| 403  | *(tier error)*   | Feature not available on your current plan. Response includes `requiredTier`. | Upgrade to the indicated tier. See [Tier limits](/guide/reference/tier-limits).                                                        |

## Project and analysis errors

| HTTP    | Code / description         | Cause                                                           | Resolution                                                                                                                                                     |
| ------- | -------------------------- | --------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 400     | `EMPTY_PATCH`              | `PATCH /api/projects/{id}` sent with no recognized fields.      | Include at least one allowed field in the request body.                                                                                                        |
| 400     | `INVALID_DESCRIPTION_TYPE` | `description` is not a string.                                  | Pass `description` as a string value.                                                                                                                          |
| 400     | `DESCRIPTION_TOO_LONG`     | `description` exceeds 5,000 characters.                         | Shorten the description.                                                                                                                                       |
| 408/504 | AI timeout                 | The audit analysis AI pipeline exceeded 180 seconds.            | Re-trigger the analysis. Use the async endpoint (`POST /api/agent/projects/{id}/audit-analysis/async`) with a polling loop if your client has a short timeout. |
| 400     | API key missing            | Audity's AI provider key is not configured or has been revoked. | Contact [support@auditynow.com](mailto:support@auditynow.com).                                                                                                 |
| 403     | Analysis limit reached     | Your plan has reached the per-project analysis limit.           | Upgrade your plan. See [Tier limits](/guide/reference/tier-limits).                                                                                            |

## Webhook errors

Webhook errors are surfaced in the Audity dashboard under your webhook delivery log. They are not returned inline to the original API caller.

| Code                      | Cause                                            | Resolution                                                                                                                                     |
| ------------------------- | ------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| `WEBHOOK_HTTPS_REQUIRED`  | Your webhook URL uses HTTP instead of HTTPS.     | Switch to an HTTPS endpoint. Audity does not deliver to plain HTTP endpoints.                                                                  |
| `WEBHOOK_TIMEOUT`         | Your endpoint did not respond within 10 seconds. | Respond immediately with a `2xx` status and process the payload asynchronously. Queue work rather than doing it inline in the request handler. |
| `WEBHOOK_DELIVERY_FAILED` | All 3 delivery attempts failed.                  | Check your endpoint logs for errors. Fix the underlying issue, then use the dashboard to replay the failed event.                              |

<Note>
  Webhooks are available on Team and Enterprise plans. See [Tier limits](/guide/reference/tier-limits) for plan details.
</Note>

## Rate limiting

| HTTP | Description                                                            | Resolution                                     |
| ---- | ---------------------------------------------------------------------- | ---------------------------------------------- |
| 429  | Rate limit exceeded. Response includes `Retry-After` header (seconds). | Back off for the indicated duration and retry. |

Rate limits by endpoint class:

| Endpoint class      | Limit        |
| ------------------- | ------------ |
| Standard reads      | 100 / minute |
| Writes              | 20 / minute  |
| Async job polling   | 120 / minute |
| Capture submissions | 30 / hour    |

## Lead errors

| HTTP | Description            | Cause                                                                 | Resolution                                                            |
| ---- | ---------------------- | --------------------------------------------------------------------- | --------------------------------------------------------------------- |
| 400  | Lead already converted | `POST .../convert` called on a lead with `surveyStatus: 'converted'`. | Check `surveyStatus` before calling convert and skip converted leads. |
| 402  | Insufficient credits   | Not enough credits to convert the lead.                               | Add credits or upgrade.                                               |

## General guidance

* Always branch on the `code` field, not the `error` string.
* A `403` with `requiredTier` means a plan upgrade is needed, not an auth issue.
* A `402` always means credits are exhausted, check `GET /api/user/credits` before batch operations.
* For transient errors (5xx, 429), retry with exponential backoff.

## Related

* [Tier limits](/guide/reference/tier-limits), plan comparison including analysis limits
* [Glossary](/guide/reference/glossary), definitions of credits and other terms