> ## Documentation Index
> Fetch the complete documentation index at: https://apidoc.bulkneo.com/llms.txt
> Use this file to discover all available pages before exploring further.

# If your number disconnects

> What a 409 really means, why retrying never fixes it, and how to reconnect without changing a line of code.

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:

```json theme={null}
{
  "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

<Steps>
  <Step title="Open Instances in the portal">
    The number will show as disconnected.
  </Step>

  <Step title="Press Show QR on that number">
    The button on each row reads **Show QR** while the number is down, and **Reconnect** while it is up. It is there either way — the stored status is a cache and it can be wrong, so pressing it on a number that only *looks* connected is the honest way to check. A fresh QR appears if, and only if, the number really is disconnected.
  </Step>

  <Step title="Scan with the same phone">
    **WhatsApp → Settings → Linked devices → Link a device.**
  </Step>

  <Step title="Done">
    The status returns to connected and sending resumes immediately.
  </Step>
</Steps>

<Tip>
  Re-scanning a number you already used today costs nothing extra. Charging is per number per day, so checking a number that turns out to be fine, or repairing one that is not, is free either way.
</Tip>

<Check>
  **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.
</Check>

## What NOT to do

<Warning>
  **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.
</Warning>

<Warning>
  **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.
</Warning>

## Handling it in code

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

```javascript Node.js theme={null}
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:

1. **Pause the number**, not the whole system — your other numbers are unaffected.
2. **Alert a person.** Nothing else will fix this.
3. **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:

```bash Check every number at once theme={null}
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:

```bash theme={null}
curl https://api.bulkneo.com/v1/instances/YOUR_INSTANCE_ID/status \
  -H "apikey: YOUR_API_KEY"
```

<Tip>
  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.
</Tip>

## 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.