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.

{
  "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 [e-mail].

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 [e-mail].
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.

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, plan comparison including analysis limits
• Glossary, definitions of credits and other terms