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

# WhatsApp LID Issue — Resolving Unknown Contacts

> Understand what WhatsApp LIDs are, why you may encounter 'could not resolve recipient' errors, and how to handle them when sending messages.

When sending messages through the WhatsApp API, you may occasionally encounter an error indicating that WhatsApp **could not resolve a recipient**. This is often related to WhatsApp's internal contact resolution system, which uses **LIDs (Linked IDs)** to identify contacts.

## What is a LID?

WhatsApp identifies contacts internally using a unique identifier called a **Linked ID (LID)**. This is separate from the phone-number-based ID (`@c.us` format) that you normally use to send messages.

| Format                | Meaning               | Usage                                                                     |
| --------------------- | --------------------- | ------------------------------------------------------------------------- |
| `201234567890@c.us`   | Phone-number-based ID | Use the full international number without `+`, spaces, or hyphens.        |
| `123456789012345@lid` | WhatsApp Linked ID    | An internal identifier managed by WhatsApp. Do not construct it manually. |

When you send a message to a phone number, WhatsApp's servers must first resolve that phone number to its internal LID. If this resolution fails, the message cannot be delivered.

## Why Does the "Could Not Resolve Recipient" Error Happen?

There are several reasons why WhatsApp may fail to resolve a recipient:

### 1. The Number Does Not Exist on WhatsApp

The most common cause. The phone number you are trying to message is not registered with WhatsApp, or the account has been deleted.

### 2. The Number is Temporarily Unreachable

A valid WhatsApp number may be temporarily unreachable due to network issues, the user changing devices, or the account being in a restricted state.

### 3. Timelock Restrictions

If your instance is under a Meta timelock restriction, WhatsApp may refuse to resolve new contacts — even if those numbers exist on WhatsApp. This is part of the restriction enforcement.

Read more: [Understanding WhatsApp Timelock Restrictions](/v2/hypersender/overview/whatsapp/whatsapp-timelock-restrictions)

### 4. WhatsApp Service Disruptions

Rarely, WhatsApp's own infrastructure may experience issues that prevent contact resolution for a short period.

## How Hypersender Handles LID Errors

When WhatsApp fails to resolve a recipient, Hypersender returns a clear error to your API request:

* **HTTP 422 status code** with a message explaining that the recipient could not be resolved
* If your instance has an active timelock, the error message includes the **remaining restriction time**
* The error helps your application distinguish between a genuine invalid number and a temporary resolution failure

## What You Can Do About LID Errors

<Steps>
  <Step title="Verify the phone number">
    Double-check that the phone number is in the correct international format (e.g., `201234567890` for an Egyptian number) and that the person actually uses WhatsApp.
  </Step>

  <Step title="Check for active restrictions">
    Look at your instance's status in the Hypersender dashboard. If a timelock warning banner is visible, the restriction is likely the cause. Wait for the restriction to expire or use a different instance.
  </Step>

  <Step title="Save the contact first">
    Use the [Upsert Contact endpoint](/v2/api-reference/whatsapp/contacts/upsert-contact) to save the number as a contact before sending a message. This can improve resolution reliability.
  </Step>

  <Step title="Check existing contacts">
    Use the [Get All Contacts endpoint](/v2/api-reference/whatsapp/contacts/get-all-contacts) to see which contacts are already known to your instance and their LID mappings.
  </Step>

  <Step title="Retry later">
    If the error is temporary (network issues or WhatsApp service disruption), wait a few minutes and retry. Hypersender's [Queued Requests](/v2/api-reference/whatsapp/queued-requests) feature can help with automatic retries.
  </Step>
</Steps>

## Working with LIDs in Your Integration

<Note>
  Always use the `@c.us` phone-number format when sending messages. Hypersender handles the LID resolution internally. You do not need to work with `@lid` identifiers directly.
</Note>

If you need to retrieve the LID for a known phone number or find the phone number for a known LID, use these endpoints:

* [Get Phone Number by LID](/v2/api-reference/whatsapp/contacts/get-phone-number-by-lid) — Look up a phone number using a LID
* [Get LID by Phone Number](/v2/api-reference/whatsapp/contacts/get-lid-by-phone-number) — Look up a LID using a phone number
* [Get All Known LIDs](/v2/api-reference/whatsapp/contacts/get-all-known-lids) — List all known LID mappings for your instance

<Card title="What is chatId?" icon="question-mark-circle" href="/v2/api-reference/whatsapp/what-is-chatid">
  Learn more about WhatsApp chat identifiers, including `@c.us` and `@lid` formats.
</Card>