Errors

Every error names its cause. The same failure has the same code on every edge.

Over HTTP the body is { "code", "message" }. Over MCP the error carries a JSON-RPC code and data.kind with the same code. The CLI prints error: <message> and exits with 1.

CodeHTTPMCPWhenWhat to do
unauthenticated401-32001No valid sign-in or token was sent, or it expired.Sign in again with sddvault login, or create a new token.
forbidden403-32003Your role or the token's access does not allow the action, for example an editor writing the constitution.Ask a project owner, or use an identity or token with the right access.
policy403-32003An organization policy or plan limit refused the request. The code is one of the reasons below.Read the message: it names the policy or limit and how to lift it.
not_found404-32002The project, spec, document, task or revision does not exist, or you cannot see it; over HTTP also a path that is no API route.Check the address (organization/project) and the number.
conflict409-32602The document changed after the revision you based your write on.Read the current revision (the error carries it), merge and write again.
claimed409-32602Another agent or person holds the claim on the task.Pick another task, or wait until the claim is released or expires.
validation422-32602The input is invalid, malformed or refused, for example an invalid status change or approving a spec with open markers, or a spec number or id in the path that is not a positive whole number.Read the message: it names the field or the allowed values.
inherited_principle422-32602A constitution write changes a principle inherited from the organization.Leave inherited principles as they are and add your own.
precondition409, 410, 413-32602The state of the target does not allow the request, it is gone, or the body is too large.Read the message and fix the state before retrying.
rate_limited429-32029Too many requests in a short time.Wait the seconds in the Retry-After header, then retry.
billing409, 422-32602The billing provider is not configured or refused a plan change.Review the billing details, or contact support.
identity_provider_refused422-32602The sign-in provider refused a change.Review the details in the message and retry.
organization_creation410, 409, 503, 422-32602Creating an organization failed. The code is one of the codes below.Follow the message and start again if the request expired.
unavailable503-32603A service SDD Vault depends on is temporarily unavailable.Retry in a moment.
internal500-32603Something failed on our side.Retry; if it persists, contact support.

Policy and plan refusals

CodeWhen
ip_not_allowedThe organization's IP allowlist does not include your network.
guests_disabledThe organization does not allow guests.
admin_only_project_creationOnly organization owners and admins can create projects.
plan_seat_limitThe plan has no more seats for the role being added.
plan_project_limitThe plan has reached its number of projects.
plan_featureThe feature is not included in the plan.
plan_mcp_call_limitThe plan's monthly MCP calls are used up; they resume on the first day of the next month.

Organization creation codes

CodeWhen
organization_request_expiredThe creation request expired; start again.
organization_already_createdThe organization was already created from this request.
organization_creation_pausedCreating organizations is paused temporarily.
bot_check_failedThe bot check failed; try again.