Commune

402payment_required

Plan does not include this

The credential may do this, but the newsletter's Commune plan does not include it. Reads outside insights stay free.

Commune reads are free and writes are paid. Two things can be metered: writes, every operation that changes something, and insights, GET /newsletters/{newsletter}/insights and GET /newsletters/{newsletter}/events. When a feature is metered, a request for it on a newsletter whose plan does not include it answers 402. Every other read keeps working on every plan, so the same credential can go on reading everything else.

The message names the plan the newsletter is on (with its billing state) and allowed_values lists the plans that include the feature. The plan belongs to the newsletter, not to the credential or to you.

This status is predictable. GET /newsletters/{newsletter}/entitlements answers the same question in advance, with the same sentence in reason and the same plan list, plus metered (whether Commune charges for the feature right now) and granted (whether a call would succeed at this moment). Read it once at the start of a run instead of finding out halfway through one. Revoking an API key is never refused for payment.

Why it happens, and how to fix it

  1. The newsletter has no Commune plan

    Most newsletters published through another provider have no Commune subscription at all, and a newsletter with no plan on record includes no metered feature. The message reads "This newsletter has no Commune plan on record."

    Fix: The newsletter's owner subscribes to the Creator plan from Account & Billing in the Commune dashboard, with that newsletter selected. Until then, use the free reads.

  2. The subscription was cancelled or the trial ended

    The plan includes the feature, but its billing state is canceled or trial_expired, which suspends it. A payment that is merely past_due does not: the grace period keeps integrations working.

    Fix: The owner renews or resubscribes from Account & Billing. Check GET /newsletters/{newsletter}/entitlements afterwards; granted turns true without any change to your credential.

  3. The plan does not include the feature

    The newsletter is on a plan that is not in allowed_values (today creator and enterprise include both writes and insights).

    Fix: The owner moves the newsletter to one of the plans in allowed_values from Account & Billing.

Retrying

No: it keeps failing until the newsletter's plan changes, which GET /newsletters/{newsletter}/entitlements will show as granted: true.

Example response

HTTP 402
{
  "error": {
    "code": "payment_required",
    "message": "Changing anything through the Commune API needs a plan that includes it. This newsletter has no Commune plan on record. Plans that include it: creator, enterprise. Reading is free on every plan, so a key that cannot write can still read everything it could before.",
    "allowed_values": [
      "creator",
      "enterprise"
    ],
    "request_id": "req_01j9c8h1q7m3n4p5r6s7t8u9v0",
    "docs_url": "https://usecommune.dev/errors/payment_required"
  }
}

Often confused with insufficient_scope, not_commune_newsletter.