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.