plan_required

HTTP 403. The request is valid and the account is in good standing; the plan does not include the feature it asked for. Nothing was rendered and nothing was billed.

Two features are gated this way: webhooks (webhook_url) and cloud delivery (pushing a finished render to your own S3 or R2 bucket). Both are on every paid plan, starting with Solo at $5 a month. The third refusal with this type is the template limit, which is a number rather than a feature. Every engine, every format, the whole API and MCP surface, and no watermark are the same on Free as on Scale.

{
  "error": {
    "type": "plan_required",
    "message": "Webhooks are not included on the Free plan. `webhook_url` needs Solo ($5.00/month) or above.",
    "docs_url": "https://galleyrender.com/docs/errors/plan_required",
    "details": {
      "feature": "webhooks",
      "plan": "free",
      "required_plan": "solo",
      "required_plan_price_usd": 5,
      "next_step": "Remove `webhook_url` from the request to render on Free, or upgrade at https://galleyrender.com/pricing.",
      "upgrade_url": "https://galleyrender.com/pricing",
      "feature_docs_url": "https://galleyrender.com/docs/webhooks"
    }
  }
}

Template limit

The third thing gated this way is how many templates of your own an account keeps: 3 on Free (and the keyless trial), 10 on Solo, 25 on Starter, and no limit on Growth and Scale. The starter library every account is created with never counts, and neither does a template you have deleted.

Only creating a template past the limit is refused — POST /v1/templates, or the MCP create_template tool. Nothing you already have is removed or switched off: every template keeps rendering, and publishing a new version of one (POST /v1/templates/:name/versions) is never limited. An account that is over its limit — one that moved to a smaller plan, or made more on Solo before Solo had a limit — keeps all of them and is refused only a new one, until deletions bring it under.

{
  "error": {
    "type": "plan_required",
    "message": "The Solo plan keeps 10 templates of your own, and this account has 14, so it cannot create another until it has fewer than 10. Every template it has keeps working, and the starter library does not count. Delete 5 you no longer use, or move to Starter ($19.00/month), which keeps 25.",
    "docs_url": "https://galleyrender.com/docs/errors/plan_required#template-limit",
    "details": {
      "feature": "templates",
      "plan": "solo",
      "template_limit": 10,
      "own_templates": 14,
      "starter_library_counts": false,
      "required_plan": "starter",
      "required_plan_price_usd": 19,
      "required_plan_templates": 25,
      "next_step": "Publish a new version of an existing template instead (POST /v1/templates/:name/versions, never limited), delete 5 templates you no longer use (DELETE /v1/templates/:name), or upgrade at https://galleyrender.com/pricing.",
      "upgrade_url": "https://galleyrender.com/pricing",
      "feature_docs_url": "https://galleyrender.com/docs/templates#how-many-you-can-keep"
    }
  }
}

details.own_templates is how many of your own the account holds now, and details.template_limit is the plan’s. details.required_plan is the cheapest plan with room for one more, and required_plan_templates is its limit — null means none.

What to do

Do not retry the same request. It will be refused identically every time — this is a statement about the account, not a transient failure. There are exactly two fixes:

Drop the option. Remove webhook_url (and poll GET /v1/renders/:id instead), or remove the delivery option and fetch the signed URL the render already returns. The same render then succeeds. At the template limit, the equivalent is to publish a new version of a template you already have, or delete one you no longer use.
Upgrade. details.required_plan names the cheapest plan that carries the feature, and details.required_plan_price_usd is what it costs a month. Pricing has the rest.

Why it is a 403 and not a 402

A quota_exceeded (402) means you have used up an allowance — waiting until the 1st, or upgrading, fixes it, and the identical request will eventually work. A plan_required means this account may not do this at all, and no amount of waiting changes that. They are different decisions for an agent, so they are different codes.

Pricing — what each plan includes
Webhooks — what you get once the plan carries them
quota_exceeded — the allowance ran out, rather than the plan

plan_required

Template limit

What to do

Why it is a 403 and not a 402

Related