/Docs
Search docs or ask a question⌘K
DocsAgent
Changelog

Errors

Error response format and error codes used across the Syntext API.

21 min read

The Syntext API uses conventional HTTP status codes and returns a consistent error shape on every failure.

Error Response Format

json
{
"error": {
"code": "not_found",
"message": "Project does not exist",
"details": { "traceId": "6f1c2a9e-3b7d-4c11-9a0e-2d5f8b4c7e10" }
}
}
NameDescription
error.code:stringbody
A stable, machine-readable error code. Match on this, not the message.
error.message:stringbody
A human-readable description of what went wrong.
error.details:objectbody
Additional context — e.g. the plan and role fields described below, or a route-specific field such as status or runId. Present on every JSON error body, because it carries traceId.
error.details.traceId:stringbody
The id of the request that failed. Always equal to the response's x-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:

text
x-request-id: 6f1c2a9e-3b7d-4c11-9a0e-2d5f8b4c7e10

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:

bash
curl https://api.syntext.dev/v1/projects/$PROJECT_ID \
-H "Authorization: Bearer $SYNTEXT_TOKEN" \
-H "x-request-id: deploy-2026-11-08.42"

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

StatusMeaning
200Success
201Resource created
202Accepted for async processing — analytics beacons, deploys, promotions and rollbacks that rebuild
400Bad request — malformed body or invalid parameters (validation_error when a schema check fails)
401Unauthorized — missing or invalid credentials
402Payment required — the feature needs a higher plan tier (plan_required), or a plan quota or the seat limit is used up (USAGE_LIMIT_EXCEEDED)
403Forbidden — valid credentials, but access is denied or your role is too low
404Not found — the resource doesn't exist or belongs to another project
409Conflict — 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)
410Gone — expired for a CLI device code that has expired, otherwise gone
413Payload too large — an avatar over 2 MB, or a glossary CSV over its caps
415Unsupported media type — an avatar that isn't PNG, JPEG, GIF or WebP
422Unprocessable entity (unprocessable_entity)
428Precondition required — authorization_pending while polling for a CLI device token
429Rate limited — see Rate Limits
500Internal error — safe to retry with backoff
502Bad gateway — a service Syntext depends on (such as GitHub or the payment provider) failed or refused the call
503Service 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

CodeStatusDescription
bad_request400The request body or parameters are invalid
validation_error400The 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_password400POST /auth/password — the current password is wrong. Accounts created with GitHub sign-in get it too; use forgot-password instead
password_unchanged400POST /auth/password — the new password equals the current one
email_unchanged400POST /auth/change-email — the new address is the one already on the account. Resend the verification link instead — see Change Unverified Email
confirmation_mismatch400DELETE /auth/account — confirmEmail is not the account's email address
invite_not_pending400Declining an invitation that was already accepted or revoked
invite_expired400Declining an invitation that has expired
terms_required400POST /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_token400/email/unsubscribe — the unsubscribe token is missing, altered, or its account no longer exists — see Unsubscribe
invalid_schedule400PATCH …/schedules/{scheduleId} — scheduledFor is not in the future. details.scheduledFor echoes it
invalid_csv400POST …/glossary/import — the CSV has no importable rows. details.errors lists { line, message }
invalid_path400An 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
unauthorized401Missing, expired, or invalid API key / token — or an API key sent to an endpoint that only accepts a signed-in session
session_revoked401The 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_required402The feature is not included in the workspace's plan. details has feature, requiredTier and currentTier — see Plan errors
forbidden403You 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_EXCEEDED402A plan quota was reached — monthly builds or AI queries, the project count, or the seat limit — see Usage limit errors
CONFIRMATION_REQUIRED400POST …/chat/run — a POST, PUT, PATCH or DELETE without confirmed: true, or a DELETE without typed: "DELETE"
invalid_reviewer400A review was assigned to its own requester, or to someone outside the workspace
invalid_webhook_url400A webhook URL is not https, or points at a private or local address — see Outbound webhooks
invite_email_mismatch403The invitation was sent to a different email address than the one on the signed-in account — see Invitation errors
email_unverified403The signed-in account's email address is not verified yet, so it cannot accept an older invitation — see Invitation errors
email_not_verified403Your 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_leave403DELETE /orgs/{orgId}/members/{memberId} — an owner tried to leave. Transfer ownership first (you become an admin), or delete the workspace or your account
self_approval403You tried to approve a review or content approval you requested yourself
role_not_allowed403An approval gate does not admit your role as an approver. details.allowed lists the roles it does admit
installation_not_owned403The project's GitHub App installation is not connected to its workspace. Reconnect the repository from the dashboard
NOT_ALLOWED403POST …/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_HOST403POST …/chat/run and the dashboard API playground — the host is, or resolves to, a private or local address
PRIVATE_SITE403/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_disabled403The add-on the endpoint belongs to (e.g. webhooks) is not enabled for the project
access_denied403POST /auth/device-token — the CLI sign-in request was denied in the browser. Stop polling
not_found404Resource doesn't exist
expired410The CLI device code has expired — on polling, lookup and approval alike. Start a new stx login
gone410Any other 410 without a more specific code
conflict409The resource changed since you last read it, or already exists (e.g. you are already a member of the workspace)
already_approved409You have already approved this content approval — or, on POST /auth/device-deny, the CLI sign-in request was already approved
device_denied409POST /auth/device-approve — the sign-in request was already denied
build_not_cancellable409The build is deploying, deployed, failed or already cancelled. details.status says which — see Cancel Build
build_cancelled409POST …/deploy — the build was cancelled while its files were uploading, so it was not queued. details.buildId
rollback_target_not_deployed409The rollback target build is not deployed. details.status says what it is — see Roll Back
rollback_target_is_preview409The rollback target is a preview build — promote it instead
rollback_unavailable409Nothing to rebuild the rollback target from: its uploaded source is no longer kept, or the project has no repository
build_in_progress409An 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_conflict409An 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_use409An approval gate still has pending approvals. details.pending counts them; switch the gate off instead, or decide them first
lint_run_in_progress409A project-wide lint run is already running. details.runId
last_owner409The change would leave the workspace with no owner — demoting the only owner. Transfer ownership first
sole_member409DELETE /orgs/{orgId}/members/{memberId} — you are the only member and tried to leave. Delete the workspace or your account instead
invite_limit_reached409POST /orgs/{orgId}/invites or …/resend — the workspace already has 10 pending (unexpired) invitations. details.max, details.pending; revoke one first
slug_taken409PATCH /orgs/{orgId} — another workspace (including a deleted one) has the slug. details.slug
active_subscription409DELETE /orgs/{orgId} — the workspace still has a renewing paid subscription. Cancel it in the billing portal first. details.tier
owns_workspaces409DELETE /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_verified409POST /auth/change-email — the account's address is already verified, so it can't be changed there
email_in_use409POST /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_unavailable409A webhook delivery can't be replayed — no stored payload (recorded before payloads were kept, or over 64 KiB)
endpoint_inactive409A webhook delivery can't be replayed because its endpoint is paused
approval_closed409The approval is already approved or rejected. details.status says which
not_scheduled409The scheduled publish has already published, failed, or been cancelled. details.status says which
term_exists409A glossary term with that name already exists in this project. details.term names it.
MEMORY_DISABLED409PATCH …/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_DISABLED409POST …/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_DISABLED409POST …/chat/run — the project hasn't turned on agent.runRequests — see Run an API Request
GATED_CONTENT409POST …/chat/sessions/{sessionId}/share — an answer in the conversation used audience-gated content, so it can't be shared
EMPTY_CONVERSATION409POST …/chat/sessions/{sessionId}/share — the conversation has no answers yet
HANDOFF_UNAVAILABLE409POST …/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_large413POST …/glossary/import — over 256 KB of CSV or 1000 rows
avatar_too_large413Avatar upload over 2 MB. details.maxBytes
unsupported_image415Avatar upload that isn't PNG, JPEG, GIF or WebP (SVG is refused)
rate_limited429Too many requests. The error includes retryAfterSeconds — under details for the editor limits.
internal_error500Unexpected server error
rollback_failed502An 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_error502GitHub refused or failed an editor request. details.githubStatus has GitHub's status; GitHub's response body is not passed through
DELIVERY_FAILED502POST …/chat/handoff — neither the support email nor a subscribed support.handoff webhook endpoint took the handoff
stripe_error502Billing details couldn't be loaded from the payment provider while loading invoices or the payment method. Try again shortly
lint_run_failed502A project-wide lint run failed (e.g. the repository could not be listed). details.runId; the run is recorded as failed
service_unavailable503A required service is temporarily unavailable. Retry with backoff
billing_unavailable503Billing is temporarily unavailable
storage_unavailable503Avatars can't be stored or served right now
not_configured503The 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.

errorLands onMeaning
email_in_use/loginAn 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/registerA GitHub sign-up without accepting the Terms, once that's required
github_failed/loginGitHub 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:

json
{
"data": { "id": "3f2a9c1e-8b4d-4e7a-9c21-5d6e7f8a9b0c", "name": "Acme Docs" },
"warnings": [
{
"code": "ignored_settings_keys",
"message": "These settings keys cannot be changed through this endpoint and were ignored.",
"keys": ["sso", "aiPersona.systemPrompt"]
}
]
}
CodeReturned byMeaning
ignored_settings_keysPATCH /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_pendingPATCH /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:

json
{
"error": {
"code": "validation_error",
"message": "newPassword: String must contain at least 8 character(s)",
"details": {
"issues": [
{ "path": ["newPassword"], "code": "too_small", "message": "String must contain at least 8 character(s)" }
],
"target": "json",
"traceId": "6f1c2a9e-3b7d-4c11-9a0e-2d5f8b4c7e10"
}
}
}
•
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.

Note

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.

Note

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:

json
{
"error": {
"code": "plan_required",
"message": "SSO requires the Pro plan or higher. This workspace is on Starter.",
"details": {
"feature": "sso",
"requiredTier": "pro",
"currentTier": "starter",
"traceId": "6f1c2a9e-3b7d-4c11-9a0e-2d5f8b4c7e10"
}
}
}
NameDescription
details.feature:string
The gated feature, e.g. sso, audit_export, translations — see the table below.
details.requiredTier:string
The lowest plan that includes the feature: free, starter, pro, or enterprise.
details.currentTier:string
The workspace's current plan. A workspace with no subscription is on free.

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.

EndpointfeatureMinimum plan
GET /projects/{projectId}/audit-logaudit_logStarter (7 days of history; Pro 365 days; Enterprise unlimited)
GET /projects/{projectId}/audit-log with actoraudit_actor_filterPro
GET /projects/{projectId}/audit-log/exportaudit_exportPro
PUT /projects/{projectId}/auth/ssossoPro
POST /projects/{projectId}/auth/sso/enforce with enforced: truessoPro
POST /projects/{projectId}/auth/sso/enable with enabled: truessoPro
GET /projects/{projectId}/analytics/annotation-coverageannotationsPro
POST /annotations/driftdrift_detectionPro
POST /annotations/sdksdk_codegenPro
POST /projects/{projectId}/sdk/generate · GET /projects/{projectId}/sdk/downloadsdk_codegenPro
PUT /projects/{projectId}/monitoring/config · POST /projects/{projectId}/monitoring/runapi_monitoringPro
POST /projects/{projectId}/i18n/translatetranslationsPro
POST /projects/{projectId}/domains · POST …/domains/{domainId}/verify · …/retry · …/confirm-readycustom_domainsStarter
The same domain endpoints for a wildcard hostname (*.docs.example.com)wildcard_domainsPro
PUT /projects/{projectId}/custom-scriptscustom_scriptsStarter
POST /integrations/discord/{projectId}/register-commandsdiscord_botStarter
PATCH /projects/{projectId}/addons/slack_bot/settingsslack_botStarter
POST /projects/{projectId}/addons/{addonType}/toggle with enabled: trueper add-on, belowper add-on
PUT /projects/{projectId}/addons/{addonType}/configper add-on, belowper add-on

Add-ons map to plans as follows:

Add-on (addonType)featureMinimum plan
mcp_server, ai_widget, slack_bot, discord_bot, custom_scriptssame nameStarter
sdk_generationsdk_codegenPro
api_monitoringapi_monitoringPro
i18ntranslationsPro
agentic_modeagentic_modePro
webhooks, changelog, postman_export, access_controlwebhooks, changelog, postman, access_gatingFree

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:

json
{
"error": {
"code": "forbidden",
"message": "Only workspace admins can perform this action.",
"details": {
"requiredRole": "admin",
"currentRole": "member",
"traceId": "6f1c2a9e-3b7d-4c11-9a0e-2d5f8b4c7e10"
}
}
}

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:

EndpointsNotes
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-controlSite access control: who can read the doc site, and the site password
POST /projects/{projectId}/webhook-endpoints · PATCH/DELETE …/webhook-endpoints/{endpointId} · POST …/{endpointId}/testOutbound webhooks. Any member can list endpoints and deliveries
POST /projects/{projectId}/audiences/{profileId}/tokenAudience access codes. accessToken is also omitted from audience responses for members
GET /orgs/{orgId}/invitesPending 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}/membersAdding 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-methodAny member can read the subscription and usage
POST /projects/{projectId}/webhook-endpoints/{endpointId}/rotate-secret · POST …/webhook-deliveries/{deliveryId}/replayAny member can read a delivery
PATCH /projects/{projectId}/addons/slack_bot/settingsAny member can read the Slack status

These need the owner role:

EndpointsNotes
DELETE /orgs/{orgId}Deletes the workspace and its projects
POST /orgs/{orgId}/transferMakes 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:

json
{
"error": {
"code": "email_not_verified",
"message": "Verify your email address to continue. Open the link we emailed you, or resend it (or fix the address) from the Syntext dashboard.",
"details": {
"resend": "POST /v1/auth/verify-email/send",
"changeEmail": "POST /v1/auth/change-email",
"traceId": "6f1c2a9e-3b7d-4c11-9a0e-2d5f8b4c7e10"
}
}
}
NameDescription
error.details.resend:stringbody
The endpoint that emails a new verification link.
error.details.changeEmail:stringbody
The endpoint that fixes a mistyped address and sends a link there — see Change Unverified Email.

It 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:

•
Sign in and out — register, log in, refresh, log out
•
Verify — resend and confirm the verification link, and change the address before verifying
•
Manage its password — change it, or reset it with forgot-password
•
•
Answer or skip onboarding
•
Accept or decline invitations — accepting a recent invitation also verifies the address

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:

json
{
"error": {
"code": "invite_email_mismatch",
"message": "This invitation was sent to a different email address.",
"details": { "traceId": "6f1c2a9e-3b7d-4c11-9a0e-2d5f8b4c7e10" }
}
}

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:

json
{
"error": {
"code": "USAGE_LIMIT_EXCEEDED",
"message": "Monthly build limit reached (100/100). Upgrade your plan for more builds.",
"current": 100,
"limit": 100,
"details": { "traceId": "6f1c2a9e-3b7d-4c11-9a0e-2d5f8b4c7e10" }
}
}

The seat limit carries its numbers in details rather than at the top level. Seats are members plus invitations that can still be accepted:

json
{
"error": {
"code": "USAGE_LIMIT_EXCEEDED",
"message": "Your free plan allows up to 2 team members. Upgrade to add more.",
"details": { "limit": "members", "max": 2, "tier": "free", "traceId": "6f1c2a9e-3b7d-4c11-9a0e-2d5f8b4c7e10" }
}
}

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.
•
Build triggers are idempotent per commit: re-triggering the same commit creates a new build but never corrupts state.
Was this page helpful? Yes No
Product
Resources
Company
© 2026 SyntextBuilt with Syntext