Errors & rate limits

Error shape

Every error response uses a consistent envelope:

{
  "error": {
    "code": "FORBIDDEN",
    "message": "Key lacks required scope: chatbots:write",
    "details": { }
  }
}

• code — a stable, machine-readable identifier.
• message — a human-readable explanation.
• details — (optional) additional structured context.

The SDKs surface this as a typed error. In TypeScript, non-2xx responses throw WizChatApiError (with status and the parsed envelope); in Python they raise WizChatApiError.

import { createWizChatClient, WizChatApiError } from '@wizchat/management';

try {
  await wizchat.getConfig('abc123');
} catch (err) {
  if (err instanceof WizChatApiError) {
    console.error(err.status, err.message);
  }
}

from wizchat_management import WizChatClient, WizChatApiError

try:
    wizchat.get_config("abc123")
except WizChatApiError as err:
    print(err.status, err.message)

Status codes

Status	Code	Meaning
400	BAD_REQUEST	Invalid input — malformed body or parameters
401	UNAUTHORIZED	Missing or invalid API key
403	FORBIDDEN	Key is valid but lacks the required scope
404	NOT_FOUND	The chatbot or resource does not exist or isn't visible to the key
422	UNPROCESSABLE_ENTITY	Partial failure on apply — see below
429	RATE_LIMITED	Too many requests — back off and retry

422 on apply

The config-as-code apply endpoint returns 422 for partial failure: execution stopped at the first failing operation. The body is an ApplyResult whose failed field is populated and whose applied field lists the operations that succeeded before it. Apply is idempotent — fix the offending section and re-run the same document. The SDK applyConfig / apply_config helpers return this result rather than throwing, so inspect result.failed.

Rate limits

The API is rate limited. When you exceed the limit you receive 429 Too Many Requests. Build clients that back off and retry — prefer exponential backoff with jitter — and avoid tight polling loops. For bulk changes, prefer a single config-as-code apply over many individual writes.

Related

• Authentication & scopes — why a request returns 401 vs 403
• Config-as-code — the 422 partial-failure flow
• API Reference — per-operation status codes