Update account

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.

auth_mode_phone_required · 20019 · 400

Provide provider_data.phone when creating the account for this authorization mode.

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 · 20019

{
  "request_id": "req_example",
  "error": {
    "code": "auth_mode_phone_required",
    "numeric_code": "20019",
    "message": "Phone number is required for this auth mode"
  }
}

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"
  }
}

unsupported_provider_auth_mode · 20018 · 400

Choose an auth_mode supported by this channel.

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 · 20018

{
  "request_id": "req_example",
  "error": {
    "code": "unsupported_provider_auth_mode",
    "numeric_code": "20018",
    "message": "Auth mode not supported by this provider"
  }
}

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"
  }
}

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"
  }
}

egress_configuration_pending · 20032 · 409

The platform default network configuration cannot currently be confirmed or loaded. This does not mean the account is logged out.

When it occurs: The operation uses platform-managed network capacity or a fixed default network configuration.

What to do: Keep request_id and check the account or creation result before another write. Wait for capacity or configuration recovery, or contact support. Do not repeatedly create accounts, change networks, or restart accounts automatically.

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

{
  "request_id": "req_example",
  "error": {
    "code": "egress_configuration_pending",
    "numeric_code": "20032",
    "message": "Account network configuration is pending verification"
  }
}

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 · 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"
  }
}

egress_change_not_supported · 20034 · 422

This account has a fixed default network; changing its region or provider through an ordinary account update is not supported.

When it occurs: The operation uses platform-managed network capacity or a fixed default network configuration.

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 · 422 · 20034

{
  "request_id": "req_example",
  "error": {
    "code": "egress_change_not_supported",
    "numeric_code": "20034",
    "message": "The requested network change is not supported"
  }
}

update_account_failed · 20003 · 500

Update account: an unclassified error interrupted this change; the resulting resource state needs confirmation.

What to do: Read the current resource state and confirm the previous outcome before repeating this change. Keep request_id; do not automatically repeat a write whose outcome is unknown.

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

{
  "request_id": "req_example",
  "error": {
    "code": "update_account_failed",
    "numeric_code": "20003",
    "message": "Failed to update account"
  }
}

update_account_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": "update_account_failed",
    "numeric_code": "20020",
    "message": "Account not found"
  }
}

update_account_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 only to a real authorization-mode change that invokes WhatsApp logout. Updating ordinary account details does not trigger this numeric detail.

What to do: Read the current resource state and confirm the previous outcome before repeating this change. Keep request_id; do not automatically repeat a write whose outcome is unknown.

Channels: WhatsApp

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

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

update_account_failed · 30021 · 500

The account was not connected to the messaging platform for this request. WhatsApp contact creation can return 500 / create_contact_failed / 30021. This does not prove logout or that the current runtime status is still disconnected; query the current status before choosing a recovery action.

When it occurs: Applies only to a real authorization-mode change that invokes WhatsApp logout. Updating ordinary account details does not trigger this numeric detail.

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

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

{
  "request_id": "req_example",
  "error": {
    "code": "update_account_failed",
    "numeric_code": "30021",
    "message": "Account is not connected to the messaging platform"
  }
}

provider_unavailable · 30002 · 502

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

What to do: Read the current resource state and confirm the previous outcome before repeating this change. Keep request_id; do not automatically repeat a write whose outcome is unknown.

Example · 502 · 30002

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