2 min read Last updated:
Errors
All errors come back as JSON with at minimum a message field.
Status codes
| Status | Meaning |
|---|---|
| 200 | OK |
| 201 | Created |
| 202 | Accepted (queued background work) |
| 302 | Redirect (file downloads to signed URLs) |
| 400 | Bad request - malformed JSON, invalid query params |
| 401 | Unauthorized - missing or invalid token |
| 402 | Payment Required - plan does not include the requested resource (e.g. surveys, funnels, AI insights) |
| 403 | Forbidden - token missing the right ability, or policy denied |
| 404 | Not found - record doesn't exist or belongs to another team |
| 409 | Conflict - e.g. AI insights regeneration already running |
| 422 | Validation failed - body details on what's wrong |
| 423 | Locked - feature locked by plan |
| 429 | Rate limited |
| 500 | Server error |
Body shapes
Validation errors:
{
"message": "The given data was invalid.",
"errors": {
"name": ["The name field is required."]
}
}
Ability errors:
{
"message": "token missing forms:write ability"
}
What to do
- Re-mint your token if you see 401.
- Read the
errorsmap for 422. - Wait + retry for 429 - the response body includes a
Retry-Afterheader. - Upgrade your plan or use the dashboard for endpoints that come back 402 / 423. The REST API and MCP server themselves are available on every plan; paywalled resources (surveys, funnels, AI insights, custom retention) are what raise 402 / 423.