plan_required

What it means

plan_required means the call needs a paid plan. The Platform API answers with HTTP status 402 and an error object shaped like {"error":{"code":"plan_required","message":"...","hint":"..."}}. The code is stable; match on the code field, never on the message text, which can change.

The hint and details.billing_url in the response point at the plan page for the account, so you can hand the link to whoever manages billing instead of digging through the console yourself.

Why you are seeing it

Two situations return this code. The first is a request for a webhook endpoint on the free Sandbox plan, which allows 0 endpoints. Polling is the supported route for event data on Sandbox: call GET /api/platform/v1/events with a cursor.

The second is a call to a write tool on a plan that does not include write tools. The message names the plan that adds the capability: Webhooks start on Starter ($19/month, or $199/year). The Sandbox plan polls GET /events instead.

endpoint_limit and quota_exceeded are the related codes. Read which one came back and check the hint for that response before changing anything on the account.

How to fix it

Choose a plan on the console Billing tab at https://onelifevibe.com/platform/#billing. The details.billing_url field in the error response links to the same page. Starter is $19/month or $199/year and covers the webhook case.

If you are on Sandbox and need event data now, do not wait on a plan change. Poll GET /api/platform/v1/events with a cursor instead of registering a webhook, and keep the cursor so you can resume from the last event you processed.

After the plan changes, retry the original call with the same request body and identifiers. Nothing in the request itself caused the error.

Handling it in code

Branch on error.code: when the code is plan_required, read hint and details.billing_url and show them to the person who can change the plan. Skip retry loops. The same request returns the same code until the plan supports the call.

Treat 402 as a configuration outcome, not a transient failure. Keep it out of the retry path you use for network timeouts and 5xx responses, and out of any alert that pages an on-call engineer.

Log the code, the hint and the endpoint you called. That record tells you whether you hit a webhook request on Sandbox or a write tool call on a plan without write tools.