What happens when the subscription becomes overdue, and why. The rule lives in one place only (the central access check) and is predictable: expensive actions are blocked, cheap reads continue.
Concepts#
- Expensive action: consumes money/resources. There are five: manual refresh
(
refresh_manual), running/sending reports (report_run), queries via API (api_query), export (export) and AI features (ia). - Cheap read: viewing an already materialized dashboard/snapshot — never blocked (it serves ready-made data, with no processing cost for the owner).
- Two billing signals: the local status (from the payment provider) and the udiApps central service (the product contract).
How the check decides (order)#
- Local status of
past_due,suspendedorcanceled⇒ blocks expensive actions (HTTP 402). The local signal is enough; it doesn't even query the central service. - Otherwise, udiApps central with
allowed: false⇒ blocks (suspended → 402; no contract → 403). - Fail-open only when there's no signal at all: non-negative local status
(
active,inactive,pending) and no response from the central service.inactive/pendingdon't block on purpose — that's the default for a new/trial workspace. - Cheap reads are never blocked (public dashboard/snapshot).
- App navigation continues: the overdue customer needs to navigate to Plans to pay — that's why navigation isn't taken down; only the expensive actions are blocked at each execution point.
Availability#
- Plans: all (the check is a core security and billing feature).
- How it works: fail-closed, covered by automated tests.
Permissions#
- Settling the payment (accessing Plans, paying) requires the owner
(
billing.manage). - The expensive-action block applies to all members of the workspace, regardless of role.
Messages the user sees (shown in Brazilian Portuguese; translated here)#
| Situation | HTTP | Message (summary) |
|---|---|---|
Payment overdue (past_due) | 402 | "Subscription payment overdue — [action] blocked until settled. Go to Plans." |
Suspended (suspended) | 402 | "Subscription suspended — [action] blocked until settled." |
Canceled (canceled) | 402 | "Subscription canceled — [action] blocked. Go to Plans to reactivate." |
| No active contract | 403 | "Workspace without an active product contract — [action] unavailable. Contact sales." |
| Workspace doesn't exist | 403 | "Workspace not found — access denied." |
Validation#
- Expensive actions return 402/403 with a ready-made message; dashboard reads stay up.
- The settlement screen (Plans) stays accessible even when overdue.
- After paying, the status goes back to
activeand expensive actions are unblocked (the central service has a ~60 s cache).
Example#
Comércio Aurora goes into past_due. Maria and the team can still see the
existing dashboards (snapshot), but can't: run a manual refresh,
send reports, export, use AI or query via the API — each attempt
returns 402 with the link to Plans. Maria (owner) goes to Plans, pays by Pix, and
within seconds everything works again.
Cost#
- The check itself uses no resources: R$ 0.
- The goal is precisely to contain cost when the account isn't in good standing.
Security#
- A single, fail-closed rule: an invalid workspace id never "slips through by mistake".
- The
/api/v1API applies a fail-closed rate limit (per key and per workspace) and the subscription check before touching the paid datalake. - Separating cheap reads from expensive actions avoids "taking down" people who only consume.
Limits#
- The REST query API (
/api/v1) is in early access and not yet open for external use — don't use it as a production route. - The fail-open is intentional and restricted to the "no negative signal" case (new/trial workspace); it isn't a bypass.
- Reactivation depends on the payment provider confirming the payment.
Troubleshooting#
| Symptom | Likely cause | What to do |
|---|---|---|
| Everything returns 402 | subscription overdue/suspended/canceled | owner settles it in Plans |
| 403 on expensive actions | no active product contract | contact sales |
| Dashboard opens, but doesn't refresh | cheap read ok, expensive action blocked | settle it to unblock refresh/AI/export |
| I paid and it's still blocked | central service cache (~60 s) | wait and try again |
Next steps: go back to the Administration index or review Plans and Consumption and quotas.