plan_limit_reached

HTTP status: 403 Forbidden

The request is well formed, but it would take the organization past one of its plan’s caps, or it acts on a webhook subscription that is already over one. The plan_limit object names the cap, and next_actions lists a request you can make next.

It shares a status code with forbidden, which is about the token’s role. Branch on error to tell the two apart. A token with a higher role gets the same answer here, and so does a retry, until the organization frees a slot or changes plan.

Which requests return it

Request	Cap
POST /api/v1/orgs/{org}/projects	Projects per organization
POST /api/v1/orgs/{org}/projects/{project}/environments	Environments per project
POST /api/v1/orgs/{org}/projects/{project}/flags	Active flags per project
POST /api/v1/orgs/{org}/projects/{project}/flags/{flag}/restore	Active flags per project
POST /api/v1/orgs/{org}/webhooks	Webhook subscriptions per organization
PUT /api/v1/orgs/{org}/webhooks/{id} with isEnabled: true	Webhook subscriptions per organization
POST /api/v1/orgs/{org}/webhooks/{id}/test	Webhook subscriptions per organization
POST /api/v1/orgs/{org}/webhooks/{id}/deliveries/{deliveryId}/redeliver	Webhook subscriptions per organization

Archived flags don’t count toward the flag cap. Restoring one adds an active flag, so a full project refuses the restore as well. The pricing page lists each plan’s caps.

The last three webhook rows come from a plan change the organization didn’t choose, such as a lapsed payment. A downgrade you make yourself needs the extra subscriptions deleted first. When an organization lands on a plan that allows fewer webhook subscriptions than it has, the oldest ones up to the new cap keep delivering and the rest are suspended. Turning a suspended subscription back on, sending it a test event or redelivering to it gets this error until a slot frees up or the plan changes. Editing a suspended subscription that is still enabled works as usual. A disabled subscription still holds its slot, so delete one to free it.

The plan_limit object

Field	Type	Description
resource	string	The capped collection: projects, environments, flags or webhooks
plan	string	The organization’s plan, spelled the way GET /api/v1/orgs/{org} returns it
max	integer	The cap. Environments and flags are counted per project

The plan field uses the API’s plan names, so the Free plan appears as Solo even though message calls it Free, the name the dashboard shows.

How to fix

• Follow next_actions. It lists what the capped collection already holds, so you can use an existing project, environment or webhook rather than create another.
• Free a slot. Delete a project, environment or webhook subscription you no longer need, or archive a flag.
• Upgrade the organization’s plan in the dashboard.

Retrying the same request returns the same error until one of these changes the count.

Example

{
  "error": "plan_limit_reached",
  "message": "Project limit of 1 reached for Free plan. Upgrade to create more projects.",
  "docs_url": "https://featureflip.io/docs/management-api/errors/plan_limit_reached",
  "next_actions": [
    { "method": "GET", "path": "/api/v1/orgs/3f2b8c1e-5d4a-4e7b-9a61-0c2d8e4f7a95/projects" }
  ],
  "plan_limit": { "resource": "projects", "plan": "Solo", "max": 1 }
}