Error Handling
All errors return JSON nested under err:
{ "err": { "message": "<message>", "code": "<symbolic_code>" } }.
code is present on validation and feature-gate errors and
defaults to INTERNAL_ERROR otherwise. HTTP status codes
follow standard semantics.
| Status | Meaning | Common causes |
|---|---|---|
| 400 | Bad Request | Validation failure, missing required field |
| 401 | Unauthorized | Missing or invalid token |
| 403 | Forbidden | Token valid but lacks the required permission or admin gate |
| 404 | Not Found | App doesn't exist OR your token can't access it (deliberately the same to avoid existence leaks) |
| 409 | Conflict | Optimistic-concurrency mismatch, idempotency-key collision, phone-number conflict |
| 429 | Too Many Requests | Rate limit hit |
| 500 | Internal | Platform error — captured in our monitoring |
Common code values:
APP_NOT_FOUND,VALIDATION_ERRORINSUFFICIENT_BALANCE,INSUFFICIENT_POOL_BALANCEEXPECTED_VALUE_MISMATCHPHONE_NUMBER_IN_USEFEATURE_FORBIDDEN(RBAC feature gate),API_KEY_SCOPE,INTERNAL_ERROR(default). Note: some ad-hoc 403s carry nocodeand fall back toINTERNAL_ERROR.
Retry recommendations:
429: backoff (start 1s, double up to 60s).500: retry once after 1s; escalate tosupport@everycallhandled.comif persistent.409on idempotency-key collision: treat as success (the prior call landed).
A route we retire does not vanish. It keeps its sign-in and answers
410 Gone with a small JSON body naming the route, the
retirement date and what to do, and every hit is logged (route and time,
never the body), so a caller we did not know about learns exactly what
happened before anything is deleted for good. Retired functions keep
their code for 90 quiet days, then go.
| Route | Retired | Code removed after | Note |
|---|---|---|---|
POST /aiengine2 |
28 October 2026 | 26 January 2027 | The old AI engine route; it could not run. |
POST /loadwebpage |
28 October 2026 | 26 January 2027 | The old web-page loader. |
POST /stripecancelauthorization,
/stripecapturepayment, /stripecreateaccount,
/stripecreatepaymentintent,
/stripecreatepayout, /stripegetaccountlink,
/stripegetdashboardurl,
/stripegetonboarduserstatus,
/stripegetpaymentactivity,
/stripegetpublickey, /stripeonboarduser,
/stripeplatformtransfer,
/striperefundpayment |
30 October 2026 | 28 January 2027 | Legacy Stripe payment routes, never part of this guide. Payments and payouts run through the Stripe Connect flow and the billing routes. |
POST /stripewebhook/{domain} |
30 October 2026 | 28 January 2027 | The per-merchant Stripe webhook; Stripe events arrive at
/webhook/stripe-connect. |
POST /createTFUser, /createTFUserAndSpace,
/getTFUserOrgIdByEmail, /getUserExistsByEmail,
/listcognitousers,
/updatecognitouserattributes,
/updatecognitouserpreferredspaceid,
/passwordlessConfirmAndLoginUser |
1 November 2026 | 30 January 2027 | Old user-administration routes, never part of this guide. Team
members are managed with /api/v1/users (Manage Team Members). |
POST /checkForSecureCredentials,
/createCalendarEvent, /deleteCalendarEvent,
/gcalconnect, /gcaldisconnect,
/getUserAvailabilitySlotsByDay,
/syncCalendarEvents, /updateCalendarEvent |
1 November 2026 | 30 January 2027 | Old calendar routes, never part of this guide. Calendars connect through Connect a Calendar and bookings run through the Bookings routes. |
POST /workflowcancel, /workflowschedule,
/human-tasks/complete and
GET /human-tasks |
1 November 2026 | 30 January 2027 | Old workflow scheduling and human-task routes, never part of this guide. |
POST /acladd, /aclharddelete,
/aiengine, /ai-engine-enhanced,
/processAtomfile, /schema,
/sendemailtousersingroup, /uploaduserfile and
GET /health |
1 November 2026 | 30 January 2027 | Older platform routes, never part of this guide. Access is managed with team roles (Manage Team Members) and knowledge uploads use Upload Content. Atom files uploaded to storage are still processed on arrival; only the route is retired. |
POST /api/v0/oauth/authorize,
POST /api/v0/oauth/query/{sid} |
1 November 2026 | 30 January 2027 | The early developer API, never part of this guide. Use an API key with the /api/v1 routes. |
GET /cbgcal, POST /processeventlog,
POST /signalheartbeat |
1 November 2026 | 30 January 2027 | An old calendar sign-in callback and two old device routes, never part of this guide. Calendars connect through Connect a Calendar. |
If you depend on a retired route, write to support with the route name before its removal date.
{ "error": "Gone", "route": "/aiengine2", "retired": "2026-10-28", "message": "The AI engine route was retired; it had not been called for over 30 days and could not run. If you still need it, write to support with the route name." }