Errors
Error response format and error codes used across the Syntext API.
The Syntext API uses conventional HTTP status codes and returns a consistent error shape on every failure.
Error Response Format
error.codeerror.messageerror.detailsstatus or runId. Present on every JSON error body, because it carries traceId.error.details.traceIdx-request-id header, which is on every response. Quote it when you contact support — it is how a failing request is found in our logs. See Request ids.Request ids
Every response — success or error, including CORS preflights — carries an x-request-id header:
By default the API generates a UUID. To correlate a call with your own logs, send your own id in the x-request-id request header and the API uses it unchanged — in the response header, in error.details.traceId, and in our logs:
An incoming id is accepted only if it matches /^[A-Za-z0-9._:-]{8,128}$/ — 8 to 128 letters, digits, ., _, : or -. Anything else (too short, too long, spaces, other punctuation) is silently replaced with a generated UUID rather than rejected, so always read the id back from the response header instead of assuming yours was kept.
HTTP Status Codes
| Status | Meaning |
|---|---|
| 200 | Success |
| 201 | Resource created |
| 202 | Accepted for async processing — analytics beacons, deploys, promotions and rollbacks that rebuild |
| 400 | Bad request — malformed body or invalid parameters (validation_error when a schema check fails) |
| 401 | Unauthorized — missing or invalid credentials |
| 402 | Payment required — the feature needs a higher plan tier (plan_required), or a plan quota or the seat limit is used up (USAGE_LIMIT_EXCEEDED) |
| 403 | Forbidden — valid credentials, but access is denied or your role is too low |
| 404 | Not found — the resource doesn't exist or belongs to another project |
| 409 | Conflict — the resource is in a state that doesn't allow the action (e.g. a build that is already deploying, a stale editor save, the last owner leaving) |
| 410 | Gone — expired for a CLI device code that has expired, otherwise gone |
| 413 | Payload too large — an avatar over 2 MB, or a glossary CSV over its caps |
| 415 | Unsupported media type — an avatar that isn't PNG, JPEG, GIF or WebP |
| 422 | Unprocessable entity (unprocessable_entity) |
| 428 | Precondition required — authorization_pending while polling for a CLI device token |
| 429 | Rate limited — see Rate Limits |
| 500 | Internal error — safe to retry with backoff |
| 502 | Bad gateway — a service Syntext depends on (such as GitHub or the payment provider) failed or refused the call |
| 503 | Service unavailable — a service Syntext depends on is temporarily unavailable. Retry with backoff |
When an error has no more specific code, its code follows from the status: 400 bad_request, 401 unauthorized, 402 plan_required, 403 forbidden, 404 not_found, 405 method_not_allowed, 409 conflict, 410 gone, 413 payload_too_large, 415 unsupported_media_type, 422 unprocessable_entity, 428 precondition_required, 429 rate_limited, 501 not_implemented, 502 bad_gateway, 503 service_unavailable, 504 gateway_timeout. Any other 4xx is bad_request — a client error is never reported as internal_error.
Error Codes
| Code | Status | Description |
|---|---|---|
bad_request | 400 | The request body or parameters are invalid |
validation_error | 400 | The body, query or a path parameter failed validation. details.issues lists each problem; a few endpoints add route-specific keys instead (e.g. details.allowed) — see Validation errors |
invalid_password | 400 | POST /auth/password — the current password is wrong. Accounts created with GitHub sign-in get it too; use forgot-password instead |
password_unchanged | 400 | POST /auth/password — the new password equals the current one |
email_unchanged | 400 | POST /auth/change-email — the new address is the one already on the account. Resend the verification link instead — see Change Unverified Email |
confirmation_mismatch | 400 | DELETE /auth/account — confirmEmail is not the account's email address |
invite_not_pending | 400 | Declining an invitation that was already accepted or revoked |
invite_expired | 400 | Declining an invitation that has expired |
terms_required | 400 | POST /auth/register — the Terms of Service and Privacy Policy weren't accepted (acceptedTerms: true and a termsVersion). Not returned yet: the requirement isn't switched on — see Register |
invalid_token | 400 | /email/unsubscribe — the unsubscribe token is missing, altered, or its account no longer exists — see Unsubscribe |
invalid_schedule | 400 | PATCH …/schedules/{scheduleId} — scheduledFor is not in the future. details.scheduledFor echoes it |
invalid_csv | 400 | POST …/glossary/import — the CSV has no importable rows. details.errors lists { line, message } |
invalid_path | 400 | An editor path would leave the docs folder (absolute, backslash, control character, empty, . or .. segment), or a delete targets something other than an .md/.mdx page. details.path echoes it |
unauthorized | 401 | Missing, expired, or invalid API key / token — or an API key sent to an endpoint that only accepts a signed-in session |
session_revoked | 401 | The session this token belongs to was signed out — by logout, a password change or reset, revoking the session, or account deletion. Sign in again; for the CLI, run stx login — see Sessions |
plan_required | 402 | The feature is not included in the workspace's plan. details has feature, requiredTier and currentTier — see Plan errors |
forbidden | 403 | You don't have access to this resource, or your workspace role is too low for the action. Role failures include details.requiredRole and details.currentRole — see Role errors |
USAGE_LIMIT_EXCEEDED | 402 | A plan quota was reached — monthly builds or AI queries, the project count, or the seat limit — see Usage limit errors |
CONFIRMATION_REQUIRED | 400 | POST …/chat/run — a POST, PUT, PATCH or DELETE without confirmed: true, or a DELETE without typed: "DELETE" |
invalid_reviewer | 400 | A review was assigned to its own requester, or to someone outside the workspace |
invalid_webhook_url | 400 | A webhook URL is not https, or points at a private or local address — see Outbound webhooks |
invite_email_mismatch | 403 | The invitation was sent to a different email address than the one on the signed-in account — see Invitation errors |
email_unverified | 403 | The signed-in account's email address is not verified yet, so it cannot accept an older invitation — see Invitation errors |
email_not_verified | 403 | Your account hasn't verified its email address, so it can't make changes yet. details.resend and details.changeEmail name the endpoints that fix it. POST /auth/device-token returns it with 400 instead — see Email verification |
owner_cannot_leave | 403 | DELETE /orgs/{orgId}/members/{memberId} — an owner tried to leave. Transfer ownership first (you become an admin), or delete the workspace or your account |
self_approval | 403 | You tried to approve a review or content approval you requested yourself |
role_not_allowed | 403 | An approval gate does not admit your role as an approver. details.allowed lists the roles it does admit |
installation_not_owned | 403 | The project's GitHub App installation is not connected to its workspace. Reconnect the repository from the dashboard |
NOT_ALLOWED | 403 | POST …/chat/run — the URL, path or method isn't in the project's endpoint catalog, or the endpoint's page is hidden from the reader |
BLOCKED_HOST | 403 | POST …/chat/run and the dashboard API playground — the host is, or resolves to, a private or local address |
PRIVATE_SITE | 403 | /v1/widget/* chat — the site is behind a password or invite-only access control, so the embeddable widget isn't available — see Embed the AI widget |
addon_disabled | 403 | The add-on the endpoint belongs to (e.g. webhooks) is not enabled for the project |
access_denied | 403 | POST /auth/device-token — the CLI sign-in request was denied in the browser. Stop polling |
not_found | 404 | Resource doesn't exist |
expired | 410 | The CLI device code has expired — on polling, lookup and approval alike. Start a new stx login |
gone | 410 | Any other 410 without a more specific code |
conflict | 409 | The resource changed since you last read it, or already exists (e.g. you are already a member of the workspace) |
already_approved | 409 | You have already approved this content approval — or, on POST /auth/device-deny, the CLI sign-in request was already approved |
device_denied | 409 | POST /auth/device-approve — the sign-in request was already denied |
build_not_cancellable | 409 | The build is deploying, deployed, failed or already cancelled. details.status says which — see Cancel Build |
build_cancelled | 409 | POST …/deploy — the build was cancelled while its files were uploading, so it was not queued. details.buildId |
rollback_target_not_deployed | 409 | The rollback target build is not deployed. details.status says what it is — see Roll Back |
rollback_target_is_preview | 409 | The rollback target is a preview build — promote it instead |
rollback_unavailable | 409 | Nothing to rebuild the rollback target from: its uploaded source is no longer kept, or the project has no repository |
build_in_progress | 409 | An instant rollback was refused because a build of the project is running or a production build is queued. details.buildId and details.status name the production build when there is one — see Roll Back |
save_conflict | 409 | An editor save, write or delete was based on a stale sha, or the branch moved. Nothing was written. details.paths and details.files describe the current state — see Save Pages |
gate_in_use | 409 | An approval gate still has pending approvals. details.pending counts them; switch the gate off instead, or decide them first |
lint_run_in_progress | 409 | A project-wide lint run is already running. details.runId |
last_owner | 409 | The change would leave the workspace with no owner — demoting the only owner. Transfer ownership first |
sole_member | 409 | DELETE /orgs/{orgId}/members/{memberId} — you are the only member and tried to leave. Delete the workspace or your account instead |
invite_limit_reached | 409 | POST /orgs/{orgId}/invites or …/resend — the workspace already has 10 pending (unexpired) invitations. details.max, details.pending; revoke one first |
slug_taken | 409 | PATCH /orgs/{orgId} — another workspace (including a deleted one) has the slug. details.slug |
active_subscription | 409 | DELETE /orgs/{orgId} — the workspace still has a renewing paid subscription. Cancel it in the billing portal first. details.tier |
owns_workspaces | 409 | DELETE /auth/account — you are the only owner of one or more workspaces. details.orgs lists { id, name }; transfer ownership or delete them first |
email_already_verified | 409 | POST /auth/change-email — the account's address is already verified, so it can't be changed there |
email_in_use | 409 | POST /auth/change-email — another account already uses the address. (As a sign-in redirect, email_in_use means something else — see Sign-in redirect errors) |
payload_unavailable | 409 | A webhook delivery can't be replayed — no stored payload (recorded before payloads were kept, or over 64 KiB) |
endpoint_inactive | 409 | A webhook delivery can't be replayed because its endpoint is paused |
approval_closed | 409 | The approval is already approved or rejected. details.status says which |
not_scheduled | 409 | The scheduled publish has already published, failed, or been cancelled. details.status says which |
term_exists | 409 | A glossary term with that name already exists in this project. details.term names it. |
MEMORY_DISABLED | 409 | PATCH …/chat/memory — the project has turned assistant memory off (aiPersona.memory: "off"), so there is nothing for the visitor to switch — see Assistant Memory |
SHARING_DISABLED | 409 | POST …/chat/sessions/{sessionId}/share — the project turned sharing off (aiPersona.sharing: "off"), or the site is behind a password or invite-only access control — see Share a Conversation |
RUNS_DISABLED | 409 | POST …/chat/run — the project hasn't turned on agent.runRequests — see Run an API Request |
GATED_CONTENT | 409 | POST …/chat/sessions/{sessionId}/share — an answer in the conversation used audience-gated content, so it can't be shared |
EMPTY_CONVERSATION | 409 | POST …/chat/sessions/{sessionId}/share — the conversation has no answers yet |
HANDOFF_UNAVAILABLE | 409 | POST …/chat/handoff and …/handoff/summary — the project has no usable support destination (no verified support email, and the webhook is off or no endpoint subscribes to support.handoff) — see Send to Support |
payload_too_large | 413 | POST …/glossary/import — over 256 KB of CSV or 1000 rows |
avatar_too_large | 413 | Avatar upload over 2 MB. details.maxBytes |
unsupported_image | 415 | Avatar upload that isn't PNG, JPEG, GIF or WebP (SVG is refused) |
rate_limited | 429 | Too many requests. The error includes retryAfterSeconds — under details for the editor limits. |
internal_error | 500 | Unexpected server error |
rollback_failed | 502 | An instant rollback could not be completed. The site still serves what it served before; details.buildId names a failed rollback row when one was written |
github_error | 502 | GitHub refused or failed an editor request. details.githubStatus has GitHub's status; GitHub's response body is not passed through |
DELIVERY_FAILED | 502 | POST …/chat/handoff — neither the support email nor a subscribed support.handoff webhook endpoint took the handoff |
stripe_error | 502 | Billing details couldn't be loaded from the payment provider while loading invoices or the payment method. Try again shortly |
lint_run_failed | 502 | A project-wide lint run failed (e.g. the repository could not be listed). details.runId; the run is recorded as failed |
service_unavailable | 503 | A required service is temporarily unavailable. Retry with backoff |
billing_unavailable | 503 | Billing is temporarily unavailable |
storage_unavailable | 503 | Avatars can't be stored or served right now |
not_configured | 503 | The feature isn't available right now — e.g. unsubscribe links or the GitHub integration. SSO endpoints return it with 400 or 404 when SSO isn't configured or enabled for the site |
Sign-in redirect errors
GitHub sign-in is a browser flow, so its errors arrive as an error query parameter on the dashboard page the browser lands on, not as JSON — see Sign In with GitHub.
| error | Lands on | Meaning |
|---|---|---|
email_in_use | /login | An account with this GitHub account's email exists but hasn't verified its address, so it isn't connected. Sign in with the password, verify the address, then connect GitHub from settings |
terms_required | /register | A GitHub sign-up without accepting the Terms, once that's required |
github_failed | /login | GitHub sign-in failed |
Warnings
Some successful responses carry a top-level warnings array next to data. A warning never changes the status code — the request did what it could — but tells you something you should act on:
| Code | Returned by | Meaning |
|---|---|---|
ignored_settings_keys | PATCH /projects/{projectId} | settings held keys that can't be changed through this endpoint. They were dropped, not stored; keys lists each one by dotted path. Always first in the array — see Update Project |
webhook_teardown_pending | PATCH /projects/{projectId}, DELETE /projects/{projectId}, DELETE /orgs/{orgId} | A GitHub webhook could not be removed yet and is recorded for retry |
Validation errors
A request that fails an endpoint's schema — body, query string, path parameters, form or headers — gets 400 validation_error in the standard shape:
details.issues — one entry per problem: path (field names and array indexes), the validator's code, and message. Use path to point at the field in your UI.details.target — what failed: json (the body), query, param, form or header.message — every issue as <path>: <issue>, joined with ; . A problem with the body as a whole is labelled body. A few endpoints replace it with a clearer sentence; details.issues is still there.Some endpoints check a value themselves and return validation_error with their own message and route-specific details keys (for example details.allowed) instead of issues.
Earlier releases answered many body validation failures with a bare error object with issues but no error.code. Every endpoint now uses the shape above.
Error codes are case-insensitive — treat NOT_FOUND and not_found as equivalent when matching.
Plan errors
A feature that is not included in the workspace's plan returns 402 with code plan_required. details tells you which feature was refused, the lowest tier that includes it, and the tier the workspace is on now:
details.featuresso, audit_export, translations — see the table below.details.requiredTierfree, starter, pro, or enterprise.details.currentTierfree.Branch on details.requiredTier to show an upgrade prompt — the message is for humans and may change. Do not retry: the request succeeds only once the workspace is upgraded.
Gated endpoints
These endpoints return 402 plan_required when the workspace (the organization that owns {projectId}) is below the tier shown. Paths are relative to https://api.syntext.dev/v1.
| Endpoint | feature | Minimum plan |
|---|---|---|
GET /projects/{projectId}/audit-log | audit_log | Starter (7 days of history; Pro 365 days; Enterprise unlimited) |
GET /projects/{projectId}/audit-log with actor | audit_actor_filter | Pro |
GET /projects/{projectId}/audit-log/export | audit_export | Pro |
PUT /projects/{projectId}/auth/sso | sso | Pro |
POST /projects/{projectId}/auth/sso/enforce with enforced: true | sso | Pro |
POST /projects/{projectId}/auth/sso/enable with enabled: true | sso | Pro |
GET /projects/{projectId}/analytics/annotation-coverage | annotations | Pro |
POST /annotations/drift | drift_detection | Pro |
POST /annotations/sdk | sdk_codegen | Pro |
POST /projects/{projectId}/sdk/generate · GET /projects/{projectId}/sdk/download | sdk_codegen | Pro |
PUT /projects/{projectId}/monitoring/config · POST /projects/{projectId}/monitoring/run | api_monitoring | Pro |
POST /projects/{projectId}/i18n/translate | translations | Pro |
POST /projects/{projectId}/domains · POST …/domains/{domainId}/verify · …/retry · …/confirm-ready | custom_domains | Starter |
The same domain endpoints for a wildcard hostname (*.docs.example.com) | wildcard_domains | Pro |
PUT /projects/{projectId}/custom-scripts | custom_scripts | Starter |
POST /integrations/discord/{projectId}/register-commands | discord_bot | Starter |
PATCH /projects/{projectId}/addons/slack_bot/settings | slack_bot | Starter |
POST /projects/{projectId}/addons/{addonType}/toggle with enabled: true | per add-on, below | per add-on |
PUT /projects/{projectId}/addons/{addonType}/config | per add-on, below | per add-on |
Add-ons map to plans as follows:
| Add-on (addonType) | feature | Minimum plan |
|---|---|---|
mcp_server, ai_widget, slack_bot, discord_bot, custom_scripts | same name | Starter |
sdk_generation | sdk_codegen | Pro |
api_monitoring | api_monitoring | Pro |
i18n | translations | Pro |
agentic_mode | agentic_mode | Pro |
webhooks, changelog, postman_export, access_control | webhooks, changelog, postman, access_gating | Free |
Turning things off is never gated. Disabling an add-on, turning SSO enforcement or the SSO gate off, listing, polling and removing custom domains, and reading existing configuration all work on any plan. A workspace that downgrades can switch off what its plan no longer includes.
POST /annotations/drift and POST /annotations/sdk take no project. They are allowed when any organization you belong to is on Pro or higher, and details.currentTier is the highest tier among your organizations. The exception: when you send the optional projectId to POST /annotations/drift (to store the report for that project's drift alerts), you must be a member of that project and the gate is that project's organization's plan.
Multi-version builds are gated without an error: below Pro, a build deploys only the default version and logs a warning — see Versioning.
Role errors
Workspace roles rank owner > admin > member. An action that needs a minimum role returns 403 forbidden when you are a member of the workspace but your role is below it. The message names the role needed, and details names both roles:
A required role of admin is satisfied by admin or owner. A 403 forbidden that is not about your role means you are not a member of the workspace that owns the resource, or this endpoint does not accept your credential. Role-gated endpoints need a signed-in member, so an API key gets 401 unauthorized — they accept only a session token. A resource that does not exist, or has been deleted, returns 404 rather than 403.
Some workflow actions depend on who you are relative to the item, not only on your role. Deciding a review needs the assigned reviewer or an admin. Editing or cancelling a schedule needs its creator or an admin. Leaving a workspace (removing your own membership) needs no role. Those failures return 403 forbidden with only details.currentRole. Approval gates use 403 role_not_allowed instead — see the Collaboration API.
Admin-only endpoints
Besides the collaboration endpoints marked admin in the Collaboration API, these need the admin or owner role:
| Endpoints | Notes |
|---|---|
PATCH /projects/{projectId} · DELETE /projects/{projectId} | Any member can still read the project |
POST /projects/{projectId}/api-keys · POST …/api-keys/{keyId}/rotate · DELETE …/api-keys/{keyId} | Any member can list keys |
POST /projects/{projectId}/domains · POST …/domains/{domainId}/retry · …/verify · …/confirm-ready · DELETE …/domains/{domainId} | Any member can list domains and poll their status |
PUT /projects/{projectId}/access-control | Site access control: who can read the doc site, and the site password |
POST /projects/{projectId}/webhook-endpoints · PATCH/DELETE …/webhook-endpoints/{endpointId} · POST …/{endpointId}/test | Outbound webhooks. Any member can list endpoints and deliveries |
POST /projects/{projectId}/audiences/{profileId}/token | Audience access codes. accessToken is also omitted from audience responses for members |
GET /orgs/{orgId}/invites | Pending invitations; tokens are never included. A plain member gets 200 with an empty list rather than 403; a non-member still gets 403 |
POST /orgs/{orgId}/invites · POST …/invites/{inviteId}/resend · DELETE …/invites/{inviteId} | Invitation management |
POST /orgs/{orgId}/members | Adding an existing user directly. Below admin this answers 403 forbidden without requiredRole/currentRole |
PATCH /orgs/{orgId} | Workspace name and slug |
PATCH /orgs/{orgId}/members/{memberId} | Changing an owner's role needs owner |
DELETE /orgs/{orgId}/members/{memberId} | Removing someone else. Any member can remove themselves (leave) |
GET /billing/invoices · GET /billing/payment-method | Any member can read the subscription and usage |
POST /projects/{projectId}/webhook-endpoints/{endpointId}/rotate-secret · POST …/webhook-deliveries/{deliveryId}/replay | Any member can read a delivery |
PATCH /projects/{projectId}/addons/slack_bot/settings | Any member can read the Slack status |
These need the owner role:
| Endpoints | Notes |
|---|---|
DELETE /orgs/{orgId} | Deletes the workspace and its projects |
POST /orgs/{orgId}/transfer | Makes another member owner; you become an admin |
GET /github/install-url?orgId=… · GET /github/installations?orgId=… | Only when orgId is sent — see Authentication |
Email verification
Accounts must verify their email before creating or changing anything. This is being rolled out: until it's switched on, nothing below is refused, and the dashboard still asks you to verify as the first step of setup.
Once it's enforced, any POST, PUT, PATCH or DELETE made by an account whose address isn't verified returns 403:
error.details.resenderror.details.changeEmailIt applies to API keys as well: a key created by an unverified account gets the same 403 on changes, with a message saying so. Reads (GET) are never refused, and neither are requests with no credential.
An unverified account can still:
The CLI sign-in is covered too. An unverified account can't approve an stx login request; polling POST /auth/device-token for one returns 400 email_not_verified — 400, not 403, so stx shows the message rather than reporting a denied sign-in — see stx login. The hosted MCP connector still reads, but refuses its write tools.
Get Session User and Get Profile report emailVerified, so a client can check before it tries.
Invitation errors
Accepting a workspace invitation (POST /v1/invites/{token}/accept) requires you to be signed in with the email address the invitation was sent to. The comparison ignores case and surrounding whitespace. Any other account gets 403:
Sign in with the invited address, or ask a workspace admin to send a new invitation to the address you use.
The invitation link is emailed only to the invited address, so for invitations sent since the current release, opening it proves you own that mailbox: an account that matches the invitation but has not confirmed its email can accept, and accepting marks the address verified. Invitations created before that cutoff (the platform's INVITE_EMAIL_PROOF_SINCE time) still need a verified address and return 403 email_unverified — open the verification link in your inbox and accept again, or ask an admin to send a new invitation. Resending an older invitation does not move it past the cutoff. See Accept Invitation.
An invitation can be accepted once. A second accept, or one racing the first, gets 400, and so does accepting an invitation that was declined, revoked or has expired. Declining has its own codes: 400 invite_not_pending for one already accepted or revoked, and 400 invite_expired — see Decline Invitation.
Usage Limit Errors
When an organization reaches a plan quota, the API returns 402 with code USAGE_LIMIT_EXCEEDED and the current usage. This applies to monthly builds (POST /projects/{projectId}/builds, POST /projects/{projectId}/deploy, POST /projects/{projectId}/deploy/promote, and POST /projects/{projectId}/deploy/rollback when the rollback has to rebuild — an instant rollback uses no quota), monthly AI queries (POST /projects/{projectId}/chat, POST /widget/{projectId}/chat), the project count (POST /projects), and the seat limit (POST /orgs/{orgId}/invites, POST /orgs/{orgId}/members). Earlier releases answered 403; match on the code rather than the status:
The seat limit carries its numbers in details rather than at the top level. Seats are members plus invitations that can still be accepted:
Current usage against each limit is returned by GET /v1/billing/usage — see Get Usage.
Retry Guidance
429 / 500: retry with exponential backoff, honouring Retry-After when it's set.402: do not retry — the workspace needs a higher plan (details.requiredTier), or the monthly quota resets on the 1st.4xx (other): do not retry — fix the request.