If your number disconnects

Every WhatsApp integration hits this eventually. Handling it properly is the difference between a five-minute fix and a queue full of failures nobody noticed.

What it looks like

Every send to that number starts returning:

{
  "success": false,
  "error": {
    "code": "instance_not_connected",
    "message": "This WhatsApp instance is not connected. Connect it before sending messages."
  },
  "request_id": "b1f2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d"
}

HTTP 409. Your key is fine, your instance_id is fine, your request is fine. The phone’s link to WhatsApp has dropped.

Why it happens

The connection works like WhatsApp Web: your number is a linked device. Links drop for ordinary reasons, none of which are the API’s doing.

The phone was off, out of signal or without internet for a long stretch.
Someone opened WhatsApp → Linked devices on the phone and removed the device.
WhatsApp has a limit on linked devices, and linking a new one pushed this one off.
The phone was reset, or WhatsApp was reinstalled.
WhatsApp ended the session for its own reasons.

The fix: re-scan the same number

Open your numbers screen in the portal

The number will show as disconnected.

Press Reconnect on that number

A fresh QR appears.

Scan with the same phone

WhatsApp → Settings → Linked devices → Link a device.

Done

The status returns to connected and sending resumes immediately.

Nothing in your code changes. The instance_id is the same. The API key is the same. No redeploy, no configuration update, no new number to tell your customers about.

What NOT to do

Do not delete the number and create a new one. A new instance gets a new instance_id, which means editing your configuration and deploying — for a problem a 30-second re-scan solves. Reconnecting the existing instance keeps everything as it is.

Do not retry the send in a loop. A 409 cannot succeed until a human scans a QR. A retry loop just burns your rate limit and fills your logs while the real problem sits unnoticed.

Handling it in code

Treat 409 instance_not_connected as pause and alert, not as a transient error.

Node.js

async function sendMessage(body) {
  const res = await fetch("https://api.bulkneo.com/v1/messages/text", {
    method: "POST",
    headers: {
      apikey: process.env.BULKNEO_API_KEY,
      "Content-Type": "application/json",
    },
    body: JSON.stringify(body),
  });

  if (res.ok) return (await res.json()).data;

  const { error } = await res.json();

  if (error.code === "instance_not_connected") {
    await pauseQueue(body.instance_id);          // stop sending on this number
    await alertOps("WhatsApp number disconnected — someone needs to re-scan the QR");
    await parkForLater(body);                     // do NOT drop the message
    return null;
  }

  throw new Error(`${error.code}: ${error.message}`);
}

Three things that matter in that snippet:

Pause the number, not the whole system — your other numbers are unaffected.
Alert a person. Nothing else will fix this.
Keep the message. Once the number is back, send it. A dropped connection should not mean a lost order confirmation.

Checking before you send

Cheap, and worth doing before a batch run:

Check every number at once

curl https://api.bulkneo.com/v1/instances \
  -H "apikey: YOUR_API_KEY"

Read connected on each entry. This returns the stored status, so it is fast and free. To force a live check of one number — after a 409, say — use:

curl https://api.bulkneo.com/v1/instances/YOUR_INSTANCE_ID/status \
  -H "apikey: YOUR_API_KEY"

Put the connected flag on an internal dashboard, or run a five-minute cron that alerts when it flips to false. Most teams discover a disconnect from a customer complaint; you can discover it from a Slack message instead.

Keeping connections stable

Use a dedicated phone or number for the integration, ideally one that stays charged, online and out of everyday use.
Do not clear linked devices on that phone as part of routine housekeeping.
Watch how many devices are linked. WhatsApp caps them, and adding a new one can evict yours.
The same number on two of your instances is refused. You get 409 number_already_connected, and the session that was already running keeps working — that is deliberate, so a stray second scan can never knock a working number offline.

Getting started

Guides

Reference

If your number disconnects

What it looks like

Why it happens

The fix: re-scan the same number

What NOT to do

Handling it in code

Checking before you send

Keeping connections stable

​What it looks like

​Why it happens

​The fix: re-scan the same number

​What NOT to do

​Handling it in code

​Checking before you send

​Keeping connections stable

What it looks like

Why it happens

The fix: re-scan the same number

What NOT to do

Handling it in code

Checking before you send

Keeping connections stable