Launch FAQ
Answers about setup, limits, test payments, pricing changes, cancellation, and recovery.
Answers about setup, limits, test payments, pricing changes, cancellation, and recovery.
Start with the paid API quickstart. Use these answers when setup or billing behaves differently from what you expected.
Sign up, choose an active builder plan, and connect GitHub in the dashboard.
Creation needs a managed repository connection. Without an active builder
subscription it returns 403 PLAN_UPGRADE_REQUIRED; a missing connection
returns 403 MISSING_CONNECTIONS. Connect and verify Stripe before the first
production publish, even for a free-only business. Stripe setup.
You host your backend and keep its runtime token in your host's secret manager.
Farther Shore hosts the customer portal and fronts your API with the gateway.
A production publish without a required origin returns BACKEND_TARGET_REQUIRED.
The current builder plans allow 1 business on Starter, 5 on Pro, and 10 on
Scale, per organization. Existing organizations can retain version-pinned
plan limits, so check the dashboard's billing page for your own allowance.
An organization without an active plan cannot create a business. Deleted
businesses do not count toward the allowance. Exceeding it at creation returns
403 RESOURCE_LIMIT_EXCEEDED.
A business program supports:
These are validation limits, not pricing-model defaults. For subscriber quotas,
rate limits, resource caps, and admission bounds, declare the controls in
business/. Meters, routes, and
diagnosing limits explain their different meanings. The
per-minute request limits on actions such as creating a business or a preview
are listed in Platform limits.
If a request is too large, reduce or split it. When a platform request is
throttled, the API returns 429 RATE_LIMIT_EXCEEDED with a Retry-After header;
wait at least that long and cap retries. See
Platform limits and
Response codes.
A preview is a branch-bound environment with its own accepted contract, gateway and portal hostnames, subscriptions, credentials, usage, and billing records. Its payments use Stripe test mode; they do not move real money. Production uses the live connected Stripe account. Preview mode is fixed when the environment is created; going live means releasing the reviewed program into production, not flipping that preview into live mode.
Use 4242 4242 4242 4242, any future expiry, and any three-digit CVC only in a
test checkout. Stripe test cards.
Preview origins can inherit the production backend binding. Your own backend's storage is separate only if you deploy and configure it that way. Use a preview-specific origin and secrets when test writes must stay isolated. A contract-changing preview push resets its subscriptions and API keys; an unchanged contract leaves them intact. Preview environments.
A published release becomes available to new subscriptions. Existing subscribers move according to the release's classified impact:
Already accepted usage retains its served rating context. It is never rerated at the new price. Fixed-version agreements retain their catalog version; negotiated terms require an agreement amendment.
Inspect Existing subscribers in the Apply Timeline or business status before releasing. Do not infer timing from the sign of a fee change alone. Plan changes and plan transitions explain the release and agreement boundaries.
A subscriber choosing another plan is a different operation: upgrades to a higher recurring fee apply immediately; equal-price changes, downgrades, and moves to the free floor wait for period end. A first paid enrollment becomes active after checkout completes.
These are your product's limits, enforced at the gateway. Requests to the Farther Shore platform itself (the CLI, dashboard and management API) have separate budgets: see Platform limits.
The gateway rejects work that cannot be admitted. These are the main mappings:
| Condition | HTTP status and code | Action |
|---|---|---|
| Request rate | 429 rate_limited | Honor Retry-After and retry only safe operations. |
| In-flight concurrency | 429 concurrency_limit_exceeded | Queue or back off until a slot clears. |
| Plan quota | 402 limit_exceeded | Wait for reset or choose an appropriate plan. |
| Monthly spend ceiling | 402 limit_exceeded | The monetary quota is exhausted; wait for reset or change the spend bound. |
| Insufficient available funding on a blocking plan | 402 credit_exhausted | Buy more prepaid value or wait for the next allowance issuance. |
| Request capacity | 413 request_too_large | Reduce or split the request. |
Read _fs.limitClass, _fs.reaction, retrySafe, and mustModify when
present. A Retry-After header can also accompany a 402 quota or funding denial;
that does not make a payment or plan problem safe to retry in a loop. Use the
actual header rather than assuming every limit has a one-minute reset.
Response codes has the full mapping.
An overage plan keeps serving after its included allowance is exhausted and bills additional usage at its catalog. A blocking plan refuses a request when its admission bound cannot be funded, even if some value remains. See Funding and allowances.
Deletion cancels live subscriptions first, including the corresponding paid subscriptions, then archives the business. It is destructive: customer access ends. It does not erase historical usage, invoices, or billing records. There is no separate archive operation to bypass cancellation.
If a required payment-provider cancellation fails, deletion returns 409
CONFLICT and leaves the business undeleted. Some subscriptions may already
have been cancelled before that failure. Resolve the reported cancellation
problem, read current state, and retry only after reviewing the impact.
Production deletion is a dashboard action. The public CLI does not expose
business delete; that command is restricted to the platform's test channel.
This restriction is about the CLI distribution, not a rule that paid production
businesses cannot be deleted. Remove a preview with env delete instead.
Stripe collects payment methods, settles payments, and handles tax, invoices, and payouts through your connected account. Farther Shore rates your measured usage, allocates included and prepaid value, and records the amount due. Do not maintain a parallel usage-price model in Stripe. Stripe setup and bill previews.
The subscribed organization's owner opens Billing in the portal and uses Cancel subscription. The managed control cancels at period end by default, so access remains until the paid period ends. Use the date returned by the operation as the cancellation confirmation. Cancellation and a downgrade to the free floor are different choices. Plan changes.
List tokens, then rotate the intended one:
farthershore backend tokens list quillby --env production --format json
farthershore backend tokens rotate quillby <tokenId> --format json
Rotation revokes the old token and returns the replacement once with the same
scope. Deliver it straight to the backend host's secret manager as
FS_RUNTIME_TOKEN, restart the service, and verify bootstrap and a gateway
request. This is a hard cutover; plan the deployment before rotating.
Runtime tokens.
Runtime tokens authenticate backends. Personal API keys authenticate subscribers. CLI credentials authenticate builders. They are not interchangeable.
Check the quickstart recovery steps,
denial diagnostics, and
CLI reference. Run farthershore <group> --help for exact flags.
For support, email [email protected]. Include the stable error code, request or decision id, environment, and release or commit you tested. Keep credentials, payment details, and runtime tokens out of the report.