API Limits

FoxNose enforces three kinds of limits on the Management API: structural plan quotas (how many projects, environments, and authentication assets your subscription allows), a request rate limit (requests per minute), and universal safety ceilings that protect the platform regardless of plan. To check the values that apply to your workspace, call GET /organizations/{org_key}/plan/ for your current plan or GET /organizations/{org_key}/usage/ to inspect live counters.

Structural Plan Quotas

These quotas come from your subscription plan. Before a create request succeeds, the API compares the current count against the plan value for that entity and rejects the call once the quota is reached. When a create request would exceed a quota, the API returns HTTP 403 with error_code: plan_limit_exceeded.

Entity	Scope	Free	Starter	Pro	Enterprise
Projects	Per organization	1	3	10	custom
Environments	Per project	2	3	10	custom
Collections	Per organization	50	200	1,000	custom
Flux APIs	Per environment	5	10	50	custom
Locales	Per environment	2	5	unlimited	custom
API keys	Per environment	5	10	50	custom
Custom roles	Per environment	0	5	20	custom
Requests per minute	Per organization	120	600	1,200	custom

Environments are counted per project, not across the whole organization: each project independently allows the plan number of environments.

Organizations are single-owner today: every organization is managed by the account that created it. Role-scoped API keys are the way to grant limited access to services and agents. Team member invitations are on the roadmap.

The Enterprise plan defaults to the Pro limits and can be raised on request. See Billing for pricing and how quotas map to plans.

403 `plan_limit_exceeded`

HTTP 403 — structural quota reached

{
  "message": "Plan limit exceeded",
  "error_code": "plan_limit_exceeded",
  "detail": {
    "entity": "flux_api",
    "current": 10,
    "limit": 10,
    "upgrade_url": "https://foxnose.net/billing/..."
  }
}

detail.entity identifies which quota was reached. The values emitted by the create endpoints are:

Entity in the request	`detail.entity` value
Project creation	`projects`
Environment creation	`environments`
Flux API creation	`flux_api`
Locale creation	`locales`
Manage or Flux API key creation	`api_keys`
Manage or Flux role creation	`roles`

API keys and roles share a single detail.entity value (api_keys / roles): the plan quota covers Manage and Flux keys (and roles) together for the environment. detail.upgrade_url links to the plan-upgrade page for the organization.

The legacy codes too_many_locales, too_many_manage_api_keys, too_many_flux_api_keys, too_many_manage_roles, too_many_flux_roles, too_many_apis, and too_many_environments are no longer returned. Every structural quota now surfaces as plan_limit_exceeded.

Rate limiting (requests per minute)

The Management API applies a per-organization request rate limit (see the table above). When you exceed it, the API returns HTTP 429 with error_code: rate_limited and a Retry-After header telling you how many seconds to wait before retrying.

HTTP 429 — rate limit exceeded

{
  "error_code": "rate_limited",
  "message": "Rate limit exceeded"
}

Rate-limited (429) responses are not billed. Retry with backoff after the interval in Retry-After.

Safety Ceilings

Safety ceilings are universal hard limits that protect the platform from runaway clients (for example, a script that loops and creates thousands of objects). They are not plan gates — every organization shares the same ceiling regardless of tier, and no upgrade raises them. Normal usage stays far below these numbers. For Collections, the per-plan quota above applies first; the ceiling is a final safety net behind it.

Entity	Ceiling	Scope	Response when reached
Components	5,000	Per environment	`403 plan_limit_exceeded` (`detail.entity: components`, no `upgrade_url`)
Collections	5,000	Per environment	`403 plan_limit_exceeded` (`detail.entity: collections`, no `upgrade_url`)
Schema versions	1,000	Per collection model or component schema	`422 too_many_versions`
Fields per version	1,000	Per schema version (including nested fields)	`422 too_many_fields`

Because ceilings are not plan quotas, the plan_limit_exceeded body for Components and Collections omits upgrade_url — upgrading your plan will not raise the ceiling.

HTTP 403 — collection safety ceiling reached

{
  "message": "Plan limit exceeded",
  "error_code": "plan_limit_exceeded",
  "detail": {
    "entity": "collections",
    "current": 5000,
    "limit": 5000
  }
}

Schema versions and fields use dedicated 422 codes instead:

HTTP 422 — schema version ceiling reached

{
  "message": "Too many versions for this schema",
  "error_code": "too_many_versions",
  "detail": null
}

If you legitimately need headroom beyond a ceiling, contact support at sales@foxnose.net.

Fixed Technical Limits

Some limits are neither plan quotas nor safety ceilings — they are fixed technical constraints that keep operations fast:

Limit	Value	Behavior
Component inheritance depth	2 levels by default	Publishing nested components beyond the permitted depth fails validation.
Object IDs per role	50	When assigning object-level permissions (for example, restricting a role to specific collections), each role can list at most 50 object IDs.
Environment toggle interval	300 seconds	Enabling or disabling an environment requires a five-minute pause between changes. Toggling sooner returns `environment_toggle_error`.

Billing — plans, pricing, and how structural quotas map to each tier.
Management API errors — the full error contract, including error_code conventions.
Flux API limits — delivery-side rate limits and structural guards.