Not Organic / Integration guides

Deployment & errors

Develop locally, deploy only the intended files, and distinguish a successful build from a working provider path.

Run the repository locally

Prerequisites: repository access, Nix with Devenv, and the pinned Bun version in package.json. Start from the project root. Setup creates a local .env from the example if needed.

Shell · local development

devenv tasks run notorganic:setup
devenv tasks run notorganic:check
devenv tasks run notorganic:build

# Run only the public surfaces:
devenv up landing docs

The development landing page uses port 4000 and docs use port 4100. Gateway and portal services need their configured dependencies. Starting a process does not prove that Convex, OpenBao, a model route, or checkout is ready.

Use the development key-generation script only for local signing keys. Keep .env out of version control and deployment archives. Never reuse those development credentials in production.

Deploy public pages

The static source is in apps/landing and apps/docs. The public build (notorganic:build-public) stages documentation in its developers/ directory; Caddy serves it at docs.notorganic.info. The website and docs share one Railway deployment. The Caddy server returns a real 404 for missing files.

Railway service configuration lives under infra/railway, with Dockerfiles under infra/docker. Deploy an isolated, reviewed snapshot to the intended project, service, and environment. Do not upload a working directory containing secrets or unrelated in-progress code.

Wait for a terminal deployment status, then check HTTPS, /healthz, navigation, assets, and a missing-file 404. A successful static-site deployment says nothing about gateway or payment availability.

Handle failures intentionally

HTTP / code	Meaning	Action
401	Invalid, expired, or replayed authorization.	Obtain fresh valid credentials or proof; avoid a retry loop.
403 / `insufficient_scope`	The caller lacks permission.	Request the required approved capability; do not broaden it silently.
403 / `realtime_consent_required`	Realtime consent is missing.	Explain processing and obtain the appropriate consent.
404 / `not_found`	The account cannot read the resource.	Check the ID and owner without revealing other accounts’ data.
400 / `invalid_idempotency_key`	Required key is missing or malformed.	Supply a stable key for the intended action.
503 / `checkout_unavailable`	The payment adapter is not configured.	Disable purchase entry points until the provider path works.
503 / `sandbox_unavailable`	Execution is not configured.	Show an unavailable state; do not report a job as started.
426 / `upgrade_required`	The deployment lacks the needed realtime upgrade adapter.	Verify WebSocket support in the deployed runtime.

JSON · illustrative error envelope

{
  "error": {
    "message": "Requested capability is not available.",
    "type": "permission_error",
    "param": null,
    "code": "insufficient_scope"
  }
}

The SDK exposes NotOrganicError with status, type, code, and param. The token-exchange helper throws a normal Error rather than that structured type. Treat returned messages as diagnostic text, not HTML.

Readiness is a sequence of proofs

Deterministic checks: typecheck, unit and contract tests, build, and configuration validation.
Deployed services: correct target, terminal successful deployment, TLS, readiness probes, and dependency access.
Authentication: real sign-in, consent, exchange, proof-bound API call, expiry, and revocation.
Paid usage: test checkout, signed webhook, one credit grant, request debit, reconciliation, cancellation, and refund.
User experience: keyboard and mobile checks, useful error states, and working privacy/support routes.

Document each result with its environment and date. Mocked tests and a marketing site returning HTTP 200 do not substitute for a provider-backed integration test.