feat: enforce daily quota and surface structured 429 with settings link

[neubig]

Enforces the daily conversation quota at conversation creation time and ensures the blocked error is properly displayed to users.

Backend

• Atomic reserve(): PostgreSQL upsert with conversation_count < limit guard; raises HTTP 429 with structured detail when limit is reached
• release(): Decrements usage when conversation start fails
• Enforcement wired into app_conversation_router.py: Reserves before starting, releases on failure
• Structured 429 detail includes message field pointing to /settings/quota

OpenHands Frontend (error display)

• retrieveAxiosErrorMessage extended to extract detail.message from structured FastAPI error responses
• type-guards.ts: New isAxiosErrorWithStructuredDetail guard
• Regression test for structured detail extraction

Stacking

PR	Scope
#180	Schema foundation: limit column + usage table
#199	Read-only usage API + settings page with countdown
#212	Org-level quota exemptions and admin API
#200	Work-email quota requests, verification, admin APIs, PostHog
This PR	Conversation enforcement, structured 429, error display

This pull request was created by an AI agent (OpenHands) on behalf of the user.

---

Enterprise server image for this PR:

ghcr.io/openhands/enterprise-server:sha-e0095e2

[linear]

OSS-9996 Limit daily conversations to 20 with support for per-user increases

Context

The linked Slack discussion converged on:

• Set a default daily conversation limit of 20.
• If a user needs more, manually increase their limit to 200 without charging them.
• If this happens frequently, automate the request/limit-increase workflow.
• The initial implementation should be pragmatic and allow manual operations before building a larger self-service system.

Slack discussion: https://allhandsai.slack.com/archives/C0A4YK70L3X/p1786657867367199

Proposed design

Implement a per-user, per-UTC-day conversation-start quota enforced server-side at the canonical V1 app-conversation creation endpoint (POST /api/conversations). The limit should be independent of the number of active sandboxes and should count a conversation once when its start request is accepted. It should apply consistently to UI, SDK/API, and integration-triggered starts that run on behalf of a user.

Policy and data model

• Add a configurable default limit in the enterprise server configuration, with the default set to None (unlimited). The OpenHands/OpenHands-Cloud Helm chart should be able to override this setting; OpenHands/saas-deploy should set the deployed SaaS default to 20. This keeps the enterprise application reusable without imposing a quota on every deployment.
• Add a nullable per-user override (for example daily_conversation_limit) to the enterprise user/org-member settings model. NULL means use the configured deployment default; any explicit integer value is valid, including values below 20, above 200, 0, or negative values if operators intentionally set them. Overrides are operational data set directly in the database for now, not a user-facing/admin API. Keep the override separate from LLM budget settings because this is a count quota, not a spend quota.
• Add a small daily usage table keyed by (user_id, usage_date) with conversation_count and timestamps, or use an equivalent atomic counter store if the deployment already has a supported Redis primitive. PostgreSQL should be the source of truth for durable accounting; do not derive enforcement from an unbounded conversation-history count on every request.
• Record the effective limit and the request's organization/trigger in structured logs/metrics, but do not duplicate mutable policy values into conversation metadata.

The quota owner should be the user, not the organization: the Slack concern is power users creating excessive conversations, while the existing conversation metadata already associates every V1 conversation with both user_id and org_id. If product later needs an organization-wide cap, it can be added as a separate policy without changing the per-user counter semantics.

Enforcement

• Add a reusable DailyConversationQuotaService and invoke it before starting the conversation task, before set_db_session_keep_open and before any sandbox is created.
• Atomically reserve one slot using a PostgreSQL upsert/update in a transaction (or an equivalent Redis atomic operation). The check-and-increment must be one atomic operation so concurrent tabs, SDK calls, and integrations cannot bypass the limit.
• Only successful start requests that reach the accepted start-task state should consume a slot. If validation fails before acceptance or the service fails to create the start task, roll back/release the reservation where possible. Decide and document whether retries of the same idempotency key reuse the original reservation rather than counting twice.
• Return HTTP 429 Too Many Requests with a stable machine-readable error code such as daily_conversation_limit_reached, plus limit, used, and reset_at (next UTC midnight). Avoid exposing other users' usage.
• Explicitly cover all alternate start paths (SDK/API, webhook/integration routes, and UI) and ensure they use the same service rather than route-specific checks.

Admin/manual increase path

For the first rollout, do not add a user-facing request flow or admin API. Support/engineering can set the per-user override directly in the database. The application must not impose a 20..200 validation range: any integer value is valid so operators can grant a smaller or larger quota, set 0/negative values according to the chosen enforcement semantics, or remove the override by setting it to NULL. Document the database field and provide an operational query/runbook separately if needed.

The initial workflow should allow support/engineering to set a user to 200 or any other required value. If this happens frequently, a later self-service request/approval workflow can be added without changing quota enforcement.

Frontend behavior

• Handle the stable 429 error code in the conversation creation mutation and show a localized message explaining that the daily limit has been reached and when it resets.
• Do not rely on a client-side count for enforcement. Optionally expose used, limit, and reset_at from a lightweight authenticated endpoint so the UI can display remaining conversations, but this is not required for the first backend-only rollout.
• Ensure integrations/SDK clients receive the structured response and do not turn the error into a generic start failure.

Migration, rollout, and observability

• Add an enterprise Alembic migration for the override/counter schema, with PostgreSQL-only types/operations consistent with enterprise migration rules.
• In the first database migration, initialize every existing user's per-user override to the then-current configured default value. New users should use NULL to inherit the deployment default unless product explicitly chooses to persist the default at creation time. Usage counters still initialize lazily on the first request for each UTC date; do not backfill historical usage.
• Keep the enterprise application default unlimited (None) and make the default configurable through the OpenHands/OpenHands-Cloud Helm chart. Set the SaaS deployment value to 20 in OpenHands/saas-deploy. This configuration should support a staged rollout without requiring an enterprise-code change.
• Add metrics for quota checks, allowed/rejected starts, effective limits, and manual overrides; alert on unexpected rejection spikes and counter/database failures.
• Decide fail-open vs fail-closed for quota-store outages. Recommended for the initial rollout: fail closed only if the service can safely distinguish a quota violation from an infrastructure error; otherwise fail open with an alert to avoid taking down conversation creation.

Acceptance criteria

• With the enterprise application default (None), a user with no override is unlimited.
• With OpenHands/saas-deploy configuring the default as 20, a user with no override can start conversations 1–20 on a UTC day and the 21st accepted start receives HTTP 429 with daily_conversation_limit_reached and a next-midnight reset timestamp.
• An explicit per-user override takes precedence over the deployment default; an override of 200 allows starts through 200 and rejects the 201st.
• Explicit per-user overrides accept any integer value and are read directly from the database; NULL falls back to the configured deployment default.
• Separate users have independent counters; organization membership and switching organizations cannot reset or multiply a user's quota.
• Concurrent start requests cannot reserve more than the configured limit.
• Failed/invalid starts do not permanently consume quota slots, and retry behavior is covered by tests.
• UI, SDK/API, and integration-triggered starts all enforce the same policy and receive the same stable error contract.
• Support/engineering can set and clear an override directly in the database; no application-level range validation or user-facing override API is required for the first rollout.
• Tests cover migration/model behavior, quota boundary conditions, UTC rollover, concurrent reservations, override precedence, error responses, and frontend error rendering.

This issue/design was prepared by an AI agent (OpenHands) on behalf of the user.

Review in Linear

[github-actions]

Coverage report

Click to see where and how coverage changed

File	Statements	Missing	Coverage	Coverage (new stmts)	Lines missing
enterprise/server/services
daily_conversation_quota_service.py					45, 103, 111-146, 150-160, 164-167
openhands/app_server/app_conversation
app_conversation_router.py					424, 436-452, 461-470, 485-492, 518-525
Project Total

This report was generated by python-coverage-comment-action

[hieptl]

Thank you! 🙏