Errors & Operations

Every tool returns a stable envelope so clients can separate successful data, permanent validation failures, transient failures, warnings, and follow-up actions.

Failure example

{
  "success": false,
  "code": "capacity_exceeded",
  "message": "The selected hosting plan has no remaining website capacity.",
  "warnings": [],
  "retryable": false,
  "nextAction": "Add capacity in the Control Panel, then retry with a new idempotency key."
}

Retry rules

Asynchronous operations

Some writes return an operationId. Call operation_get_status until the operation reaches a terminal state. Poll responsibly with increasing delays; do not start a duplicate operation while the original is pending.

Common error families

• unauthorized or forbidden: missing, revoked, expired, or insufficiently scoped API key.
• *_not_found: the resource is missing or inaccessible; the response does not reveal which.
• confirmation_required: an exact confirmation or data-loss acknowledgement is absent.
• capacity_exceeded: the existing plan cannot accept the requested resource.
• operation_in_progress: wait for the existing operation instead of creating another.