Error codes

Every error response carries a machine-readable code, a human-readable message, a requestId, and a docs link pointing back here.

Envelope

{ "error": {
    "code":      "insufficient_credits",
    "message":   "You need 150 credits but have 40.",
    "docs":      "https://www.planmysaas.com/docs/api/errors",
    "requestId": "a1b2c3…"
  } }

Authentication (401)

Code	Meaning	Fix
`missing_api_key`	No key in `X-API-Key` or `Authorization` header.	Pass the key — see auth docs.
`malformed_api_key`	Key doesn't match the `pms_live_…` shape.	Copy the key exactly as shown — no whitespace or quotes.
`invalid_api_key`	Key hash not found.	Generate a new key in Settings.
`revoked_api_key`	Key was explicitly revoked.	Generate a new one. Revoked keys can't be reactivated.

Input validation (400)

Code	Meaning
`invalid_json`	Body isn't valid JSON.
`invalid_input`	Body parsed but failed Zod validation. `message` names the offending field.

Authorisation (402 / 403)

Code	Status	Meaning	Fix
`insufficient_credits`	402	Workspace balance is less than the tool's cost.	Upgrade plan or wait for monthly refresh. See plans.
`plan_gate`	403	Tool requires a higher plan tier (e.g. Starter+).	Upgrade at /pricing.
`regen_limit`	403	Per-project regen cap reached on Free / Starter.	Upgrade to Pro for unlimited regenerations.

Rate limits (429)

Code	Meaning
`rate_limited`	60 req/min per-key exceeded. Wait `Retry-After` seconds.

Upstream / generation (502 / 504)

Code	Status	Meaning	Fix
`generation_failed`	502	The upstream AI backend returned an error or invalid JSON.	Retry. No credits charged on this response.
`generation_timeout`	504	Generation didn't return before the tool's timeout (90s-5min).	Break up very long inputs and retry.

Not found (404)

Code	Meaning
`workspace_not_found`	The workspace linked to this key was deleted.

Server (500)

Code	Meaning
`preflight_failed`	Internal error during credit preflight. Retry; if it persists, include `requestId` in a support ticket.

When to retry

Retry immediately: none — always wait a beat.
Retry after backoff: 429 (honour Retry-After), 502/504 (exponential 1s → 2s → 4s → stop).
Don't retry: 4xx except 429 — fix the input or credentials.

Still stuck? Include the requestId from the failing response in a support ticket at support@planmysaas.com.