Errors of the Mesub API

Every error has the same body:

12345678{
    "statusCode": 409,
    "message": "You are already subscribed to this plan.",
    "error": "Conflict",
    "code": "already_subscribed",
    "retryable": false,
    "request_id": "req_4f8KzQ2nVb7XcR1mT9wLp3sD"
}

Branch on code, never on message. A code is never moved to another status or reused, and is renamed only in a new Mesub-Version, but new ones are added: keep a default branch.

One exception was made before the first integrator, within 2026-10-02: plan_deleted became plan_removed, and plan_rebuilt became plan_replaced. The old names are no longer answered. Code written against them must branch on the new ones.

When retryable is true, the same request sent again unchanged may succeed later; a Retry-After header says when, in seconds. It never means "retry at once". Every route is safe to call twice.

Each route's page lists the codes that route answers. This page lists them all.

plan_ended is what Create a subscription answers once a plan's end date has passed. In the dashboard, the same code refuses closing that plan to new subscribers, changing its names, and retrying one of its payments by hand: nothing can be charged on it any more.

Three more are answered in the dashboard only, when you create a plan with an end date:

None of the three is retryable: change the date. An end date is counted in Unix seconds, and end_date_too_far is what a date sent in milliseconds gets.

The dashboard also refuses a plan on a token nobody could pay in, before you sign: mint_not_a_token (400, no token program owns that address), mint_paused and mint_transfer_hook (409), and mint_frozen_by_default, mint_non_transferable, mint_confidential_only, mint_extension_unknown and mint_display_scaled (400). How it works says what each means.

After transaction_expired, nothing was sent and the same submit cannot land. Ask for a fresh transaction, have the wallet sign it, and sign the terms again if terms.message changed.

What Retry a payment answers besides the codes above: