# Errors

> The problem+json format and every error code, with what to do.

Errors are `application/problem+json` with a stable `code`, a human `detail`, a `request_id`, and when there is one, a `hint` (the next step, in one sentence) and a `fix` (`{ "url" }` to show the user, or `{ "tool" }` to call). Every response has a `Request-Id` header.

The `type` is `https://neuropage.io/about/documentation/api#<code>`, which opens that code's entry below.

## Error codes

### invalid_request

**400.** The body is not valid JSON, or the asset type is unknown. **What to do:** Fix the request. Sending it again unchanged fails again.

### unauthorized

**401.** The API key is missing, unknown or revoked. **What to do:** Send Authorization: Bearer np_live_... with a key from Settings, API & MCP.

### insufficient_credits

**402.** The workspace has fewer credits than the job costs. Nothing was charged. **What to do:** Add credits at fix.url, or send fewer leads.

### spend_cap_reached

**402.** The job would take this API key past its monthly credit cap. Nothing was charged. **What to do:** Send fewer leads, or ask a workspace owner to raise the cap at fix.url. Caps reset on the 1st (UTC).

### plan_required

**403.** A write (any method but GET, or an MCP tool that creates or changes something) on a workspace with no paid plan or trial with a card. Reads still work. **What to do:** Show the user fix.url and stop writing. GET /workspace shows the same state in plan.

### not_found

**404.** The id is unknown, malformed, or belongs to another workspace. Over MCP with OAuth: the workspace slug is not yours, or you are in no workspace yet. **What to do:** Use an id this workspace returned. No workspace yet: create one (fix.url, or create_workspace over MCP).

### campaign_not_eligible

**409.** The campaign_id is not active with automatic page generation on. **What to do:** Leave out campaign_id, or fix the campaign at fix.url.

### idempotency_conflict

**409.** The Idempotency-Key was used in the last 24 hours for a different request. **What to do:** Use a new key for a new request. Send the exact same request to get the first job back.

### brand_not_ready

**409.** The brand is still being read from its website. **What to do:** Wait for the brand job with GET /jobs/{id}, then send the request again.

### template_not_usable

**409.** The template call to action has no destination. **What to do:** Show the user fix.url to finish the template in the app.

### validation_failed

**422.** A field is invalid, or every lead was rejected. errors[] lists each field. **What to do:** Fix the listed fields and send again.

### too_many_leads

**422.** More than 25 leads in one job. **What to do:** Split the leads into jobs of 25 and send them one at a time.

### rate_limited

**429.** A limit was reached. The limit field says which one. **What to do:** Wait the Retry-After seconds, then send the same request again.

### internal_error

**500.** A bug on our side. It is logged with the request_id. **What to do:** Retry once. If it repeats, contact support with the request_id.

### temporarily_unavailable

**503.** The API is switched off, or a page could not be started. Any charge was refunded. **What to do:** Wait the Retry-After seconds and send the same request again.
