Errors
Ramose errors are tagged and safe to branch on. Public errors explain what a caller can do next without exposing hidden resources, policy internals, storage identities, or query plans.
New here? Start with Troubleshooting.
Data-plane request errors
Section titled “Data-plane request errors”| Tag | Meaning | Caller action |
|---|---|---|
TxRejected | A commit violated the catalog or storage constraints | Refresh authoritative state; change the intent before retrying |
Unavailable | The service is temporarily unable to serve the request | Honor retry guidance and retain stale data |
InvalidRequest | A data-plane request is malformed | Fix the caller; do not repeat unchanged |
DatabaseNotFound | The requested public route is not available | Verify the deployment URL and route |
Unauthorized | Authentication or authorization failed | Refresh identity or stop; do not reveal hidden state |
QueryBudgetExceeded | A valid query exceeded configured work | Narrow filters, projection, recursion, or page size |
InternalError | An unexpected server failure occurred | Show a generic message and correlate server logs |
NetworkError | The request did not reach a conclusive response | Keep queued work and reconnect |
OperationRejected | The authoritative operation refused the intent | Present the public reason; retry only after a meaningful change |
Query, catalog, and MCP codes
Section titled “Query, catalog, and MCP codes”| Code | Meaning | Caller action |
|---|---|---|
invalid_query | Query grammar, type, bound, or cursor is invalid | Fix the query; do not repeat unchanged |
unknown_definition | A public catalog reference is unknown | Rediscover or update the client catalog |
catalog_changed | The inspected catalog token is stale | Rediscover and rebuild the request |
query_budget_exceeded | A valid query exceeded configured work | Narrow filters, projection, recursion, or page size |
invalid_input | Input failed the operation schema | Correct input from the catalog |
inaccessible | A database, definition, entity, or target cannot be revealed | Stop or ask the user for access |
operation_rejected | The authoritative operation refused the intent | Present the public reason; retry only after a meaningful change |
invocation_conflict | An invocation id identifies a different prior intent | Fix caller state; never silently repeat as new work |
inaccessible intentionally covers missing and unauthorized cases when distinguishing them would disclose information. .one() may also produce NotOne; schema policy validation may fail before deployment.
A rejected receipt rolls back that optimistic layer and reapplies later layers. Preserve user-authored input when the UI offers a corrected new invocation.
The browser client resumes database synchronization and replays durable queued invocations. It does not blindly repeat invalid queries, policy denials, domain rejections, or invocation conflicts.
UI guidance
Section titled “UI guidance”pendingquery state: show an initial skeleton because no complete local answer exists.stalequery state: keep the complete result visible and label connectivity or catch-up.rejectedreceipt: identify the action, show its public reason, and display authoritative state after rollback.- unauthenticated: pause protected work and start session recovery without clearing another principal’s data into the new session.
- inaccessible: do not reveal whether the requested resource exists.