Knowledge capacity and plan limits

Every Oddlynew organization plan includes continuously refilling input, read, and search knowledge capacity. An operation reserves a typical-cost estimate up front, renews a short lease while it runs, and settles its measured cost afterwards. A capacity refusal means one of these buckets could not fund the reservation. The refusal states the share of the allowance that is left (availablePercent), the share the operation needs (requiredPercent), a reason, and the time it can run (retryAt). Its blockingScopes field names the bucket.

What each blocking scope means

target_organization: the organization's plan budget for this lane is exhausted. It refills continuously, so short waits usually resolve it. If normal usage keeps exhausting it, take the Pro plan on the billing account that pays for the organization, or raise that account's monthly budget, since a Pro organization's daily refill grows with it: https://oddlynew.com/pricing
actor_within_target: your per-user pacing bucket inside the organization is exhausted. This protects the organization's budget from a single runaway client, and more plan is not the primary remedy: reduce concurrency, batch related work, and honor the retry time.
shared_free_grant: the pool shared by all of an account's free organizations is exhausted. Upgrading to a paid plan removes this bucket entirely.

How a well-behaved client responds

Honor Retry-After or retryAt exactly; do not poll sooner.
When retryAt is null there is no reliable automatic retry time: retry the same operation later. The refusal reserved nothing, so the operation does not need to change.
A refusal whose reason is operation_too_large is not a budget state: the single operation is larger than the lane's per operation ceiling, so no amount of waiting admits it, whatever the percentages say. Split it into smaller operations, for example fewer blocks per editDocument batch. A reason of insufficient_capacity means waiting until retryAt helps.
Reuse an idempotency key only for an ambiguous retry of the same logical operation; use a fresh UUIDv7 for each deliberate new attempt.
Treat 429 as a capacity refusal and 503 as temporary platform unavailability; neither is an error in your request.

The plans

Every organization has three capacity lanes, sized by the plan that covers it. An organization is either free or covered by the Pro plan of the billing account that pays for it, or, by arrangement, by Enterprise. Allowances are calibrated over time and are not published as numbers: what you see is the share of each lane that is left. Everything below is capacity: the pricing page owns money.

Each lane is drawn on by a different kind of work:

Input: every committed mutation, and the search rows that mutation causes to be indexed again. Deletes are free.
Read: every request, and more for larger amounts of canonical content returned.
Search: every request, each provider leg that runs, and the volume the search has to scan.

Every lane works the same way on every plan:

Daily refill: what the lane gives back over a full day, added continuously rather than as one nightly grant.
Reservoir: the most unused capacity the lane can bank, which is what lets a quiet organization burst.
Per operation ceiling: the largest single operation the lane admits, however full the reservoir is.
Per actor reservoir: the smaller bucket each member or agent holds inside the organization's, so one busy actor cannot drain the whole plan. Its refill matches the organization's.

Free

Free is for trying things out: reading the docs, wiring up a first client, keeping a small personal organization alive.

Pro

The plan you can buy is Pro, held by a billing account: its organizations get large lanes whose daily refill grows with the account's monthly budget. One Pro plan covers every organization on the account.

Enterprise

Enterprise is arranged by contacting us rather than through checkout, and it is also the shape a sponsored public-interest organization receives.

The shared free pool

Every free organization has its own plan lanes, and all free organizations belonging to one account additionally draw on a single shared pool, so creating more free organizations does not multiply the free grant.

A refusal that names the shared_free_grant scope comes from this pool. The pool refills daily and the refusal says when to retry. Creating more organizations does not enlarge it: a paid organization has its own budget and never draws on the pool.

Where you see your capacity

The billing page of your organization shows, for each lane, the share that is left and when it is full again. The refusal contract for clients lives at https://oddlynew.com/rate-limits.md. The plan comparison for humans is https://oddlynew.com/pricing.