Errors
A failed call answers with an HTTP status and a JSON body holding an error object: a stable code to branch on, a message a person can read, and sometimes details.
The error envelope
{
"error": {
"code": "SUBSCRIPTION_PAYMENT_REQUIRED",
"message": "Your last payment didn't go through. Update your payment method to keep using Scaffold.",
"details": {
"reason": "payment"
}
}
}Branch on the code; the message is written for a person to read.
Codes
34 documented
AUTH_CODE_REQUIRED400The 6-digit code is missing.
Returned by POST /billing/subscription/cancelBILLING_NOT_REACTIVATABLE400There is no scheduled cancellation, or the paid period already ended.
Returned by POST /billing/subscription/reactivateBILLING_PLAN_INVALID400Unsupported plan. BILLING_PLAN_NOT_PURCHASABLE — starter (Free) needs no checkout.
BILLING_PLAN_NOT_PURCHASABLE400BILLING_PLAN_INVALID — unsupported plan. BILLING_PLAN_NOT_PURCHASABLE — starter (Free) needs no checkout.
Returned by POST /billing/checkout/sessionBILLING_PLAN_UNCHANGED400Returned by POST /billing/subscription/changeDOCUMENT_EDIT_OPERATIONS_INVALID400No edits, more than 64, or one edit longer than 100 KB.
Returned by POST /documents/{documentId}/edits/batchDOCUMENT_REVISION_DECISIONS_REQUIRED400Choose at least one tracked change decision.
Returned by POST /documents/{documentId}/revisions/applyDOCUMENT_XML_PATCH_PAYLOAD_INVALID400expected_xml, replacement_xml, or target_xpath was missing or empty, or an XML fragment was longer than 256 KB.
Returned by POST /documents/{documentId}/edits/xml-patchSSO_HANDOFF_INVALID400Unknown, used or expired handoff code.
Returned by POST /auth/sso/exchangeUPLOAD_PART_NUMBERS_INVALID400More than 10,000 part numbers, or one outside 1 to 10,000.
AUTH_SESSION_INVALID401Returned by POST /auth/sessions/revoke-allAUTH_SESSION_REQUIRED401FREE_DOCUMENT_LIMIT_REACHED402The org's paid plan cannot be used right now. Returned by every gated work-product route (uploads, documents, runs), not only this one. SUBSCRIPTION_PAYMENT_REQUIRED is the only lock: an open Stripe payment problem. A plan limit on Free returns FREE_DOCUMENT_LIMIT_REACHED or FREE_TEMPLATE_LIMIT_REACHED.
Returned by POST /uploadsFREE_TEMPLATE_LIMIT_REACHED402The org's paid plan cannot be used right now. Returned by every gated work-product route (uploads, documents, runs), not only this one. SUBSCRIPTION_PAYMENT_REQUIRED is the only lock: an open Stripe payment problem. A plan limit on Free returns FREE_DOCUMENT_LIMIT_REACHED or FREE_TEMPLATE_LIMIT_REACHED.
Returned by POST /uploadsSUBSCRIPTION_PAYMENT_REQUIRED402The org's paid plan cannot be used right now. Returned by every gated work-product route (uploads, documents, runs), not only this one. SUBSCRIPTION_PAYMENT_REQUIRED is the only lock: an open Stripe payment problem. A plan limit on Free returns FREE_DOCUMENT_LIMIT_REACHED or FREE_TEMPLATE_LIMIT_REACHED.
Returned by POST /uploadsBILLING_ROLE_REQUIRED403Only an org owner or admin can manage billing; members can still read the subscription and entitlements.
BILLING_TESTER_CODE_INVALID403The tester access code is invalid or not enabled. Also BILLING_ROLE_REQUIRED — only an org owner or admin can manage billing; members can still read the subscription and entitlements.
Returned by POST /billing/checkout/sessionINVITE_REQUIRED403Sign-up named an existing orgId without a valid invitation; joining an organization takes an invite.
Returned by POST /auth/verifyORG_SCOPE_FORBIDDEN403STORAGE_KEY_FORBIDDEN — storageKey is not under this org's prefix in Scaffold's bucket; ORG_SCOPE_FORBIDDEN — it is not for this upload id.
Returned by POST /uploads/multipart/{uploadId}/part-urlREVISION_DECISION_REQUIRES_PERSON403With record_decision false (the agent withdrawing its own proposals), a requested change was not proposed by Scaffold (its author does not start with "Scaffold Assistant"). Only a person can decide it, in the review pane. error.details.change_ids lists the refused ids; nothing is applied.
Returned by POST /documents/{documentId}/revisions/applySECURITY_VERIFICATION_FAILED403The code was wrong or expired. Also BILLING_ROLE_REQUIRED — only an org owner or admin can manage billing; members can still read the subscription and entitlements.
Returned by POST /billing/subscription/cancelSTORAGE_KEY_FORBIDDEN403StorageKey is not under this org's prefix in Scaffold's bucket; ORG_SCOPE_FORBIDDEN — it is not for this upload id.
AUTH_USER_NOT_FOUND404No active account exists for this email in the requested organization. Sign up first (intent sign_up).
Returned by POST /auth/verifyBILLING_FREE_NOT_AVAILABLE409The workspace is on a paid plan (live, ended or with a payment problem); manage it from Billing instead.
Returned by POST /billing/free/startBILLING_PORTAL_UNAVAILABLE409503The org has no Stripe customer on file (pilot/comp grant, or never checked out).
Returned by POST /billing/portalBLOB_STORE_NOT_CONFIGURED409This deployment has no blob store configured.
Returned by POST /uploads/multipart/initiateDOCUMENT_EDIT_CONFLICT409The document changed after editing began.
Returned by POST /documents/{documentId}/contentDOCUMENT_TEXT_AMBIGUOUS_MATCH409find_text matched more than one place.
UPLOAD_DOWNLOAD_UNAVAILABLE409No blob storage is configured, or no file is stored yet.
Returned by GET /uploads/{uploadId}/downloadDOCUMENT_TEXT_NOT_FOUND422find_text was not found, occurrence was out of range, or the edit produced no tracked revisions.
DOCUMENT_XML_PATCH_REVISIONS_REQUIRED422The patch did not produce tracked revisions.
Returned by POST /documents/{documentId}/edits/xml-patchBILLING_CHECKOUT_RATE_LIMITED429Returned by POST /billing/checkout/sessionSSO_EXCHANGE_RATE_LIMITED429Returned by POST /auth/sso/exchangeSTRIPE_PORTAL_SESSION_FAILED502Stripe did not return a portal session.
Returned by POST /billing/portal