Every refusal in makermap carries three things:
- code - a stable
UPPER_SNAKE identifier to branch on. It does not change when the wording does. - message - what happened, in a sentence, with the specific numbers in it.
- hint - the next call that would succeed.
If you are reading a refusal and still do not know what to do, that is a bug in the refusal, and worth reporting as one.
The ones you will meet first
| Code | What it means |
|---|
GATE_NOT_PASSED | A gate has an open condition. The hint names it. |
PLAN_LIMIT_REACHED | A ceiling on the current plan. Nothing was removed; the next create was refused. |
PRODUCT_READ_ONLY | This product is over the plan's product limit, so it takes no writes. It still reads and still exports. |
PLAN_FEATURE_REQUIRED | The capability is not in this plan. The message names the cheapest plan that has it. |
CREDITS_EXHAUSTED | Not enough agent credits for a metered call. Everything unmetered still works. |
SPEND_CAP_EXCEEDED | The window's spend cap would be exceeded by this write. |
AGENT_ACTION_DENIED | An agent principal attempted a protected act. No scope grants it. |
The full list is in the error reference.
Two that look alike and are not
PLAN_LIMIT_REACHED means you hit a ceiling - archive something or move up a plan and the same call works. PLAN_FEATURE_REQUIRED means the capability is not in this plan at all, so retrying can never succeed. They are separate codes so an agent does not sit in a retry loop against something that will never change.
When a plan gets smaller
A ceiling can drop below what you already have - a free trial ends, a grant is withdrawn, a subscription moves down. Nothing is deleted when that happens. The products over the line go read-only: they read, they export, their whole history is there, and only changes are refused with PRODUCT_READ_ONLY.
An owner or admin then picks which ones keep working, on the billing page. Until somebody picks, the most recently worked-on ones stay writable, so an organization nobody has logged into does not sit in an undefined state. Products still over the line after 30 days are archived - which is recoverable, not a deletion. Moving up a plan releases all of them at once.