Errors say what broke and which field. Limits say when to come back.
The error object
Every failed request answers with this body. type is one of the types below, param names the field at fault, details adds what some types need, and request_id is what support finds the failure by.
422 Unprocessable Content
1{2"error":{3"type":"validation_failed",4"message":"title is required.",5"param":"title",6"request_id":"err_01jbz6f7h9k1m3n5q7s9t1v3w5",7"doc":"https://scaffold.llc/docs#errors"8}9}
Types
400invalid_requestThe body isn't valid JSON, has a field the command doesn't take, or a header is malformed. param names the field.
401unauthorizedThe token or session is missing, revoked or expired.
402credits_exhaustedThe workspace is out of credits. Top up to start more runs.
402cap_reachedThe workspace reached the monthly credit cap its owner set or its plan's build minutes, or the project's app its monthly email quota or an hourly email limit.
403forbiddenThe call needs write access, an owner, or a console session, or it sent the session cookie from a page outside Scaffold.
403plan_requiredThe feature needs the Paid plan, or more of it than Free's limit does. details names it and the limit.
403lockedToo many wrong passwords or codes in a row. details.wrong says which, and details.locked_until when to try again.
403challenge_endedThe two-factor step of a sign-in expired or already finished. Sign in again.
403project_suspendedScaffold suspended the project: its app's users cannot sign in, its env and settings take no changes and it cannot connect Stripe until it is unsuspended.
403wrong_passwordYour current password, asked again before changing how you sign in, is wrong.
403sign_in_againYou have no password, so a change to how you sign in needs a sign-in from the last 5 minutes. Sign in again, then retry.
403terms_not_acceptedThe Terms or Privacy Policy changed and the person has not accepted them yet, so only reads run. A person accepts them at the console page details.accept_at names; no agent or token can.
403provider_unfinishedSigning in with GitHub or Google did not finish. details.return_to is the console page to go back to.
404not_foundNothing with that id that you can see.
409conflictThe name is taken, or the change clashes with the current state.
409stale_versionThe record changed since you read it. details holds the current one.
409restorable_projectA deleted project still holds the name. details says how to restore it.
409terms_changedThe Terms or Privacy Policy changed since the page loaded. Reload it to read the versions details names.
409secret_shownA retry of a command whose secret is shown only once. details names what it created and its command_id.
413storage_fullThe file would take the workspace's files past its plan's cap. Delete files, or upgrade on Free.
422validation_failedA field is missing, has the wrong shape or breaks a rule. param names it.
422idempotency_key_reusedThe Idempotency-Key was used for a different request.
429rate_limitedToo many requests. Retry-After says when to try again.
429too_many_streamsThe credential, or the app of the project, holds too many open streams. Close one first.
500internalSomething failed on our side. Quote the request_id to support.
501not_implementedThe command is in the catalog but not built yet.
501not_configuredThis Scaffold has no provider the command needs, like Stripe or customer Postgres, set up. A retry fails the same way.
502upstreamA provider Scaffold relies on, like Stripe, failed. Try again.
503unavailableScaffold is busy or in maintenance. Retry after the seconds in Retry-After.
Limits are per token unless noted. Every response carries RateLimit-Remaining and RateLimit-Reset, and a 429 adds Retry-After in seconds.
Plan limits
Projects2 on Free, any number on Paid
Deploys in any 24 hours15 on Free, any number on Paid
Build minutes a month120 on Free, 1,000 on Paid
Custom domains1 on Free, any number on Paid
File storage1 GB on Free, 10 GB on Paid
Server code and workersPaid only
Apps sleep when idle for5 minutes on Free, 10 minutes on Paid
Each person owns one Free workspace, and gets 50 starter credits in it once their email is verified. Past a Free limit a call answers plan_required with the limit in details.limit, and past Paid's build minutes cap_reached. A workspace that moves to Free keeps what it has but adds nothing past these.
Lists return has_more and next_cursor. Pass the cursor back as starting_after. Each list's limit field says how many it returns at most.
Idempotency
Retry-safe write
1curl-X POST https://scaffold.llc/v1/tasks\2-H"Authorization: Bearer $SCAFFOLD_TOKEN"\3-H"Idempotency-Key: launch-2026-10-29"\4-H"Content-Type: application/json"\5-d'{ "workspace_id": "ws_01jbz5m8q6e4w3r2t1y0v9h8g7", "title": "Ship the booking page" }'
Send an Idempotency-Key header and a retried write returns the first result instead of running twice. Keys last 24 hours. The same key with a different request answers idempotency_key_reused.
Versions
Send Scaffold-Version: 2026-10-01 to pin behaviour. Without the header, requests use the version your token was created on, and the SDK always sends its own. Breaking changes ship as a new date, listed in the changelog first.