last verified · 2026-07-16
Errors
Every error response is JSON with at least an error string:
{ "error": "ticket not found" }A few operations attach extra fields on top of that envelope — for example,
an invalid ticket-status transition also carries from/to/message
(see Tickets), and a validation failure on webhook event
types carries a valid array of the accepted values.
Status codes
| Name | Type | Description |
|---|---|---|
400 | Bad request | Malformed JSON, a missing required field, an invalid enum value (e.g. an unrecognized memory_type or webhook event_type), or a query param that fails validation. |
401 | Unauthorized | No credential was sent, the Bearer token is invalid/revoked, or the Clerk session is missing. See Authentication. |
403 | Forbidden | Your tenant doesn't have access to the project_key (alias: venture_key) you asked for, or your API token has been revoked by an administrator. |
404 | Not found | The resource id/slug doesn't exist, or the project_key (alias: venture_key) doesn't exist. |
409 | Conflict | A duplicate unique value (a ticket/decision/memory that already exists), an invalid ticket status transition, or resolving a decision that's already resolved. |
429 | Too many requests | You've exceeded your tenant's rate-limit budget for this window. Retry-After (seconds) is set on the response. |
500 | Internal server error | Something failed on our side. These are logged; if one persists, it's worth reporting. |
Rate-limit headers
Every successful /api/v1/* response also carries:
| Name | Type | Description |
|---|---|---|
X-RateLimit-Limit | string | Your tenant's request budget for the current window. |
X-RateLimit-Remaining | string | Requests left in the current window. |
Retry-After | string | Seconds until the window resets. Only present on a 429. |
Rate limits, auth, and project access are all checked before your handler runs, so a 401/403/429 never partially executes a write.