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.