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.
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.
{
"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. |
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. |
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. |
| 403 | Analysis limit reached | Your plan has reached the per-project analysis limit. | Upgrade your plan. See 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. |
Webhooks are available on Team and Enterprise plans. See Tier limits for plan details. Rate limiting
| HTTP | Description | Resolution |
|---|
| 429 | Rate limit exceeded. Response includes Retry-After header (seconds). | Back off for the indicated duration and retry. |
| 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.
- Tier limits, plan comparison including analysis limits
- Glossary, definitions of credits and other terms
