Reference

Errors

Every error from the REST API is JSON with a stable code. MCP tools return the same codes as tool errors that read Error <code>: <message>.

{
  "error": {
    "code": "plan_conflict",
    "message": "The plan changed since you read it",
    "hint": "Read the plan again (wavefront_get_strategy or GET …/plan) and redo the edit on it",
    "details": { "plan_version": 13, "base_plan_version": 12 }
  }
}

Branch on code, never on message, which may change.
hint is a next step in plain words, when there is one. details holds structured data, such as retry_after on a 429.
Each code always comes with the same HTTP status. Retry 429 after details.retry_after seconds, and 5xx with backoff. Don't retry a 4xx unchanged.

Codes

Code	Status	Meaning	What to do
`unauthorized`	401	No credential, an invalid or revoked API key, or an MCP OAuth token sent to /v1 (which takes API keys only).	Send a valid wf_live_ key in the Authorization header, or sign in again.
`forbidden`	403	The caller can't do this: the key lacks a scope (details.missing), the role is too low, or only a person in the web app can do it.	Use a key with the named scope, or have the right person do it in the web app.
`human_approval_required`	403	Only a person in the web app can approve this.	Ask an owner or editor to approve it in the web app.
`not_found`	404	No such route, item or workspace, or a workspace you don't belong to. A key for another workspace gets this too.	Check the id and the workspace slug.
`invalid_request`	400	The body or query is malformed or fails validation. The message names the field.	Fix the request. Retrying it unchanged gives the same error.
`idempotency_conflict`	409	An Idempotency-Key was reused with a different body.	Use a new key for a different request.
`conflict`	409	Something changed or is in progress: a stale base_version, a strategist turn still running, or a write that lost a race.	Read the current state, then retry.
`plan_conflict`	409	The plan changed since the base_plan_version you sent (details.plan_version).	Read the plan again and redo the edit.
`assignment_exists`	409	An active generation already exists for this assignment.	Poll that generation instead of starting another.
`revision_in_progress`	409	A revision of this version is already running.	Wait for it to finish.
`approval_mismatch`	409	The stored package no longer matches what was approved.	Review and approve the version again in the web app.
`not_approved`	409	The version isn't approved.	A person approves it in the web app first.
`last_owner`	409	The change would leave the workspace without an active owner.	Make someone else an owner first.
`email_not_allowed`	422	Sign-up isn't open to this email address yet.	Use an invited address, or contact support.
`workspace_limit`	409	You already own the most workspaces one person can have.	Use an existing workspace, or contact support.
`daily_budget_exceeded`	429	The workspace reached its daily spending limit (the trailing 24 hours).	Retry after details.retry_after seconds, or an owner raises the limit in Settings.
`service_budget_exceeded`	429	Wavefront reached its service-wide daily limit.	Retry after details.retry_after seconds.
`concurrency_limit`	429	Too many generations are queued or running in the workspace.	Retry after details.retry_after seconds, or an owner raises the limit in Settings.
`insufficient_funds`	402	The credit balance can't cover the minimum for this kind (details.balance_credits, details.required_credits).	An owner adds credits on the billing page (details.billing_url), then retry.
`plan_required`	402	The workspace has no plan for this feature, for example after the trial ends (details.feature, details.billing_url).	An owner chooses a plan on the billing page.
`too_many_attempts`	429	Too many wrong sign-in codes for this address.	Wait an hour, then request a new code.
`rate_limited`	429	A per-person, per-workspace or provider rate limit was reached.	Retry after the Retry-After header or details.retry_after seconds.
`unpriced_model`	422	The model configured for this work can't be billed yet.	Contact support. Retrying won't help.
`not_waiting_for_input`	409	Answers were sent to a generation that isn't waiting for input.	Read the generation's status first.
`invalid_state`	409	The item is in the wrong state for this action. The message says which.	Read its state, then act on it.
`context_too_large`	422	A document, an import or the documents together are too large, or the required documents don't fit what a draft can read.	Remove or shorten documents.
`context_read_only`	409	The workspace's documents are managed outside Wavefront.	Change them where they are managed.
`profile_reference_missing`	422	workspace.yaml names a document that doesn't exist (details.field, details.path).	Add the document, or fix the reference.
`slug_exists`	409	The slug or name is already in use. details names the existing item.	Pick another, or use the existing one.
`publication_active`	409	Another publication or withdrawal of this content at this destination is in progress.	Wait for it to finish, then retry.
`schedule_exists`	409	The content already has a schedule at this destination (details.schedule_id).	Change that schedule instead.
`destination_file_present`	409	The item is still at the destination.	Remove it there, then mark the publication withdrawn.
`manual_withdraw_required`	409	The destination can't delete this item for you.	Remove it at the destination by hand, then mark the publication withdrawn.
`destination_copy_rejected`	422	The draft's text breaks the destination's rules, so the destination would refuse it.	Request a revision that fixes the flagged text.
`model_output_invalid`	502	The model returned output Wavefront couldn't use. Usually seen as a failed generation's error.	Retry, or start the generation again.
`email_unavailable`	503	Email can't be sent right now.	Retry later.
`google_not_connected`	409	Google Search Console and Analytics aren't connected.	An owner connects Google in Settings → Integrations.
`google_reconnect_required`	409	Google access was revoked or expired.	An owner connects Google again.
`google_unavailable`	502	Google failed to answer.	Retry later.
`bing_not_connected`	409	Bing Webmaster Tools isn't connected.	An owner connects Bing in Settings → Integrations.
`bing_reconnect_required`	409	Bing refused the stored API key.	An owner connects a new key.
`bing_unavailable`	502	Bing failed to answer.	Retry later.
`slack_not_connected`	409	Slack isn't connected.	An owner adds Wavefront to Slack in Settings → Integrations.
`slack_unavailable`	502	Slack failed while connecting.	Try connecting again.
`teams_not_connected`	409	Microsoft Teams isn't connected.	An owner pastes a Teams workflow webhook URL in Settings → Integrations.
`import_not_connected`	409	The import source (Google Drive, Notion or Confluence) isn't connected.	An owner connects it in Settings → Integrations.
`import_reconnect_required`	409	The import source's access was revoked or expired.	An owner connects it again.
`import_unavailable`	502	The import source failed to answer.	Retry later.
`task_sync_not_connected`	409	Asana or Trello isn't connected.	An owner connects it in Settings → Integrations.
`task_sync_reconnect_required`	409	The tool refused the stored token, or the owner who connected it left.	An owner connects it again.
`task_sync_project_missing`	409	The chosen project or board was deleted or archived.	The owner who connected picks another.
`task_sync_unavailable`	502	Asana or Trello failed to answer.	Retry later.
`social_unavailable`	502	The social posting service failed to answer.	Retry later.
`misconfigured`	503	Wavefront is missing a setting this action needs.	Contact support. Retrying won't help.
`internal`	500	An unexpected error.	Retry. If it keeps happening, contact support with the time and the request.