Limits & guardrails
Comwit Cloud puts a few deliberate guardrails in place to keep your projects safe and predictable. Some are hard limits (a value the API enforces), some are safety checks (it refuses an operation that could hurt the platform), and some are features that are designed but not yet live. This page collects them all in one place so you know what to expect before you hit them.
If you are brand new, you don’t need to memorize any of this — start with Quickstart and come back here when something gets rejected.
At a glance
Section titled “At a glance”| Guardrail | Where it applies | What happens |
|---|---|---|
| App env values are plain only | Apps | secret: true is rejected with 400 |
| Lists are unpaginated | API (all list routes) | All items returned; pagination is planned |
| Query token TTL is bounded | Databases | ttl_seconds must be 1–1800 |
| Remote SQL request and response size | Databases | 250 statements, 50 KiB each, 900 KiB total SQL, 8 MiB normalized response |
| PITR is copy-only and asynchronous | Databases | Restore creates a new sibling database; it never rewinds the source |
| Protected database tenants | Databases | Lifecycle ops rejected with 403 |
| Active project-domain limit | Domains | New domains rejected once the limit is hit |
| Domain purchase | Domains | Planned, not yet live |
Idempotency-Key + async operations | API | Required for SQLite seed creation; the same key safely replays the same request |
| Hybrid database tokens returned once | Databases | Never stored — copy it immediately |
| Planned Hrana Gateway body limits | Databases | 8 MiB request and 8 MiB response after Gateway rollout |
| Storage names are global | Storage | Name becomes the exact provider bucket; conflicts return 409 |
| Storage delete requires an empty bucket | Storage | Objects are never erased implicitly |
| Presigned URL lifetime | Storage | 60–3600 seconds |
Databases
Section titled “Databases”See Manage databases and Run SQL for the full flows.
- Hybrid connection tokens are shown once and never stored. When you create
or rotate a Hybrid database, the response includes a
database_token. Comwit never keeps a copy of your raw tenant token — copy it into your app’s secret store immediately. If you lose it, rotate the token to get a fresh one (the previous token then stops working). - Query token TTL is bounded to 1–1800 seconds. Short-lived query tokens
(used by the console SQL editor and
POST /v1/databases/{database}/query-token) take attl_secondsvalue that must fall between1second and1800seconds (30 minutes). Use these for transient SQL access so you never expose the durable connection token to a browser session. - Project-scoped remote SQL is bounded. The project-scoped query route,
POST /v1/projects/{projectId}/databases/{databaseId}/query, accepts at most250statements,50 KiBof UTF-8 SQL per statement, and900 KiBof SQL in total. The encoded JSON body has a6 MiBtransport ceiling, and the normalized result envelope has an8 MiBceiling. Statements run in order; after a SQL failure, later statements are skipped. An explicit transaction left open at the end is rolled back and returns422. The route is live; its matchingcomwit databases executecommand is available incomwitv0.1.6 and newer. - The planned Database Gateway has separate 8 MiB request and response limits.
After the Gateway rollout, it supports
POST /v1/{tenant}/v2/pipeline,POST /v1/{tenant}/v3/pipeline, andPOST /v1/{tenant}/v3/cursorover HTTPS. It does not support WebSocket, protobuf, or CDC. A request over the limit is rejected with413; an oversized or unavailable upstream response is not a successful SQL result. - PITR creates a new database and never mutates the source. Restore is
asynchronous, accepts exactly one timestamp, generation, or saved alias, and
rejects future timestamps. The restored database’s token is returned once.
Server-owned reconciliation resumes active operations after a platform-api
restart; an open browser or CLI poll is not required for completion. There is
no in-place rewind or automatic promote/swap. The PITR routes are live;
corresponding CLI commands are available in
comwitv0.1.6 and newer. - Platform-critical database tenants are protected. A small set of Louhi
tenants (for example
louhi-appandcomwit-db-synthetic) are guarded by the platform. Suspend, resume, delete, rotate, query, query-token, and restore operations against a protected tenant are rejected with403. This is a launch safety guard, not a substitute for normal project authorization. db.cloud.comwit.iois a data endpoint only. Management, docs, and debug paths are blocked on the public database listener. All lifecycle operations go through the platform API, not the data host.
See Environment variables for details.
- Environment values are plain only. Setting
secret: trueon an app environment variable is rejected with400(“secret app env values are not enabled”). The live policy does not use a managed secret backend for app env, so store plain config here and keep real secrets out until a secret backend is intentionally enabled. See Deploy an app for how env values are applied.
Storage
Section titled “Storage”See Storage overview and Public delivery and presigned URLs.
- Names are globally unique. The selected name is the exact R2 bucket name; Comwit does not add a hidden project prefix.
- Deletion requires an empty bucket. A non-empty bucket returns
409 bucket_not_empty; deleting an app never cascades to Storage. - Public activation is asynchronous. Poll the detail route until public
access, domain, and TLS are active before using
public_base_url. - Presigned URLs live for 60–3600 seconds and authorize exactly one object operation.
- S3 compatibility follows the backing R2 surface. AWS-only services and every possible S3 feature are not implied.
Domains
Section titled “Domains”See Bring your own domain for the delegated-DNS flow.
- There is a per-project limit on active project domains. A configurable cost/quota guard caps how many domains a single project can have onboarded at once. The limit is checked before the Route 53 hosted zone is created, so you’re told up front rather than mid-operation.
- Domain purchase (registrar) is planned, not live. Delegated DNS for a domain you already own is fully live. Buying a brand-new domain through Comwit is designed but not yet implemented.
See the API overview and Errors & idempotency for behavior across all routes.
- Lists are currently unpaginated. Every
listroute (databases, apps, builds, domains, records, projects) returns all items in one response. Page-size and page-token pagination is planned but not yet live. - Generic idempotency keys and async operations are planned. The API is
synchronous wherever the upstream control plane is synchronous. Several specific
spots are already retry-safe today — project-domain create returns the existing
domain if present, hosted-zone creation uses a deterministic caller reference,
DNS record delete treats “already gone” as success, and app domain
attach/finalize and app delete are re-entrant. A general-purpose
Idempotency-Keyheader plus operation resources for long-running workflows is planned, not yet live.
Where each guardrail comes from
Section titled “Where each guardrail comes from”- Database limits and protected tenants → Run SQL and Manage databases
- App env policy → Environment variables
- Project-domain limit and purchase status → Bring your own domain
- Pagination and idempotency → Errors & idempotency