Start code authentication

Read HTTP status, error.code and error.numeric_code together in the context of the current operation. Numeric codes are strings. Keep request_id for diagnosis; it is not an idempotency key or a task identifier.

invalid_request · 10000 · 400

Check the JSON body and required fields.

What to do: Correct the parameters for this operation and channel before requesting again. Repeating an unchanged invalid request will not resolve the error.

Illustrative JSON; message varies with the actual cause · 400 · 10000

{
  "request_id": "req_example",
  "error": {
    "code": "invalid_request",
    "numeric_code": "10000",
    "message": "Invalid request parameters"
  }
}

invalid_target_workspace · 11003 · 400

The workspace override target is empty or malformed. Remove the override header and use the API key belonging to the intended workspace.

When it occurs: Applies when the request includes the X-Workspace-Id workspace override header.

What to do: Correct the parameters for this operation and channel before requesting again. Repeating an unchanged invalid request will not resolve the error.

Illustrative JSON; message varies with the actual cause · 400 · 11003

{
  "request_id": "req_example",
  "error": {
    "code": "invalid_target_workspace",
    "numeric_code": "11003",
    "message": "Invalid target workspace"
  }
}

provider_invalid_request · 30001 · 400

Check the channel-specific fields and formats.

What to do: Correct the parameters for this operation and channel before requesting again. Repeating an unchanged invalid request will not resolve the error.

Illustrative JSON; message varies with the actual cause · 400 · 30001

{
  "request_id": "req_example",
  "error": {
    "code": "provider_invalid_request",
    "numeric_code": "30001",
    "message": "Provider rejected the request"
  }
}

unsupported_action · 30005 · 400

This account action is not recognized; use a documented action.

What to do: Use a channel and action listed as supported. Repeating the same request does not add capabilities or grant beta access.

Illustrative JSON; message varies with the actual cause · 400 · 30005

{
  "request_id": "req_example",
  "error": {
    "code": "unsupported_action",
    "numeric_code": "30005",
    "message": "Action not supported"
  }
}

invalid_api_key · 11001 · 401

Check whether the API key is correct and enabled.

What to do: Keep request_id and the structured codes, and investigate the current operation before taking another action.

Illustrative JSON; message varies with the actual cause · 401 · 11001

{
  "request_id": "req_example",
  "error": {
    "code": "invalid_api_key",
    "numeric_code": "11001",
    "message": "Invalid API key"
  }
}

missing_api_key · 11000 · 401

Add the X-Api-Key header.

What to do: Keep request_id and the structured codes, and investigate the current operation before taking another action.

Example · 401 · 11000

{
  "request_id": "req_xxx",
  "error": {
    "code": "missing_api_key",
    "numeric_code": "11000",
    "message": "Missing X-Api-Key header"
  }
}

workspace_override_forbidden · 11002 · 403

The request attempts a workspace override that this API key is not allowed to use. Remove the override header and use the API key belonging to the intended workspace.

When it occurs: Applies when the request includes the X-Workspace-Id workspace override header.

What to do: Keep request_id and the structured codes, and investigate the current operation before taking another action.

Illustrative JSON; message varies with the actual cause · 403 · 11002

{
  "request_id": "req_example",
  "error": {
    "code": "workspace_override_forbidden",
    "numeric_code": "11002",
    "message": "Workspace override is not allowed"
  }
}

target_workspace_not_found · 11004 · 404

The overridden workspace was not found or is unavailable. Verify workspace ownership, remove the override header and use the intended workspace’s API key; repeated requests do not grant access.

When it occurs: Applies when the request includes the X-Workspace-Id workspace override header.

What to do: Check the target identifier, resource ownership and current workspace. Do not treat a confirmed missing or inaccessible target as a temporary service failure to retry automatically.

Illustrative JSON; message varies with the actual cause · 404 · 11004

{
  "request_id": "req_example",
  "error": {
    "code": "target_workspace_not_found",
    "numeric_code": "11004",
    "message": "Target workspace not found"
  }
}

account_already_authorized · 20016 · 409

The account has already completed authorization and this action refuses duplicate authorization. Refresh the authorization state and reuse the completed result; do not repeatedly authorize or cancel in a loop.

What to do: Keep request_id and the structured codes, and investigate the current operation before taking another action.

Illustrative JSON; message varies with the actual cause · 409 · 20016

{
  "request_id": "req_example",
  "error": {
    "code": "account_already_authorized",
    "numeric_code": "20016",
    "message": "Account is already authorized; re-authentication is not required"
  }
}

account_binding_not_found · 30006 · 409

The account has no active channel connection binding; check its status.

What to do: Query authorization and runtime status, then choose refresh, start or reconnect only when appropriate for the intended state and channel. A connection problem alone does not prove logout. Confirm running before dependent business operations.

Illustrative JSON; message varies with the actual cause · 409 · 30006

{
  "request_id": "req_example",
  "error": {
    "code": "account_binding_not_found",
    "numeric_code": "30006",
    "message": "Account is not bound to an available server"
  }
}

duplicate_provider_account · 20015 · 409

This channel identity is already connected to another account in this workspace.

What to do: Keep request_id and the structured codes, and investigate the current operation before taking another action.

Illustrative JSON; message varies with the actual cause · 409 · 20015

{
  "request_id": "req_example",
  "error": {
    "code": "duplicate_provider_account",
    "numeric_code": "20015",
    "message": "A provider account with the same identity already exists in this workspace"
  }
}

provider_account_mismatch · 20017 · 409

The channel identity in the request does not match the account binding.

What to do: Keep request_id and the structured codes, and investigate the current operation before taking another action.

Illustrative JSON; message varies with the actual cause · 409 · 20017

{
  "request_id": "req_example",
  "error": {
    "code": "provider_account_mismatch",
    "numeric_code": "20017",
    "message": "Authenticated provider account does not match the bound account; re-scan with the original account"
  }
}

provider_not_ready · 30009 · 409

The connection is not ready. Check authorization and runtime_status before retrying.

What to do: Query authorization and runtime status, then choose refresh, start or reconnect only when appropriate for the intended state and channel. A connection problem alone does not prove logout. Confirm running before dependent business operations.

Illustrative JSON; message varies with the actual cause · 409 · 30009

{
  "request_id": "req_example",
  "error": {
    "code": "provider_not_ready",
    "numeric_code": "30009",
    "message": "Provider client is not ready"
  }
}

provider_not_ready · 30014 · 409

The provider instance needed by this account is missing. This is a runtime availability problem, not proof that authorization expired.

What to do: Query authorization and runtime status, then choose refresh, start or reconnect only when appropriate for the intended state and channel. A connection problem alone does not prove logout. Confirm running before dependent business operations.

Channels: WhatsApp

Illustrative JSON; message varies with the actual cause · 409 · 30014

{
  "request_id": "req_example",
  "error": {
    "code": "provider_not_ready",
    "numeric_code": "30014",
    "message": "Provider instance is missing"
  }
}

provider_not_ready · 30015 · 409

The provider runtime is stopped. Confirm whether that is intentional before starting it; a stopped runtime does not itself mean logout.

What to do: Query authorization and runtime status, then choose refresh, start or reconnect only when appropriate for the intended state and channel. A connection problem alone does not prove logout. Confirm running before dependent business operations.

Channels: WhatsApp

Illustrative JSON; message varies with the actual cause · 409 · 30015

{
  "request_id": "req_example",
  "error": {
    "code": "provider_not_ready",
    "numeric_code": "30015",
    "message": "Provider runtime is stopped"
  }
}

run_auth_action_failed · 20010 · 500

Run an authorization action: the authorization action failed; check the existing flow rather than assuming authorization must restart.

What to do: Query the current authorization flow and check whether user action is required. Do not start another authorization attempt merely because this request failed; do not resubmit an expired or finished session.

Illustrative JSON; message varies with the actual cause · 500 · 20010

{
  "request_id": "req_example",
  "error": {
    "code": "run_auth_action_failed",
    "numeric_code": "20010",
    "message": "Failed to run auth action"
  }
}

run_auth_action_failed · 20020 · 500

Check account_id and use an X-Api-Key for the workspace that owns the account. An account not found in this workspace cannot be accessed with this key.

When it occurs: Applies when the account is not found; the existing HTTP status and operation code are preserved, while numeric_code identifies the missing account.

What to do: Check the target identifier, resource ownership and current workspace. Do not treat a confirmed missing or inaccessible target as a temporary service failure to retry automatically.

Illustrative JSON; message varies with the actual cause · 500 · 20020

{
  "request_id": "req_example",
  "error": {
    "code": "run_auth_action_failed",
    "numeric_code": "20020",
    "message": "Account not found"
  }
}

run_auth_action_failed · 30010 · 500

The provider could not complete the operation. message can include the original cause after “Provider operation failed:”; the reason text varies and is not a stable program interface.

When it occurs: Applies when the channel supplies no more specific failure classification; the current operation’s error is preserved.

What to do: Query the current authorization flow and check whether user action is required. Do not start another authorization attempt merely because this request failed; do not resubmit an expired or finished session.

Channels: WhatsApp

Illustrative JSON; message varies with the actual cause · 500 · 30010

{
  "request_id": "req_example",
  "error": {
    "code": "run_auth_action_failed",
    "numeric_code": "30010",
    "message": "Provider operation failed"
  }
}

provider_adapter_not_found · 30004 · 502

The channel service is unavailable. Check status or try again later; confirm the result before retrying writes.

What to do: Query the current authorization flow and check whether user action is required. Do not start another authorization attempt merely because this request failed; do not resubmit an expired or finished session.

Illustrative JSON; message varies with the actual cause · 502 · 30004

{
  "request_id": "req_example",
  "error": {
    "code": "provider_adapter_not_found",
    "numeric_code": "30004",
    "message": "Provider adapter unavailable"
  }
}

provider_unavailable · 30002 · 502

The channel service is unavailable. Check status or try again later; confirm the result before retrying writes.

What to do: Query the current authorization flow and check whether user action is required. Do not start another authorization attempt merely because this request failed; do not resubmit an expired or finished session.

Example · 502 · 30002

{
  "request_id": "req_example_provider_unavailable",
  "error": {
    "code": "provider_unavailable",
    "numeric_code": "30002",
    "message": "Provider service unavailable"
  }
}

provider_unavailable · 30010 · 502

The provider could not complete the operation. message can include the original cause after “Provider operation failed:”; the reason text varies and is not a stable program interface.

What to do: Query the current authorization flow and check whether user action is required. Do not start another authorization attempt merely because this request failed; do not resubmit an expired or finished session.

Channels: WhatsApp

Example · 502 · 30010

{
  "request_id": "req_example_operation_failed",
  "error": {
    "code": "provider_unavailable",
    "numeric_code": "30010",
    "message": "Provider operation failed: Example operation could not be completed"
  }
}

provider_unavailable · 30021 · 502

WhatsApp was not connected when this operation ran. The original connection message is retained. This does not prove logout or expired authorization and does not automatically reconnect, resend or change account state.

What to do: Pause operations that require the connection. First call POST /v1/accounts/{account_id}/runtime/refresh, recover according to the latest state and confirm runtime_status=running before business requests. Confirm the previous write result before resending.

Channels: WhatsApp

Example · 502 · 30021

{
  "request_id": "req_example_connection_disconnected",
  "error": {
    "code": "provider_unavailable",
    "numeric_code": "30021",
    "message": "example operation: websocket not connected"
  }
}