Skip to main content
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. 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

​
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

1

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

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

Save the contact first

Use the Upsert Contact endpoint to save the number as a contact before sending a message. This can improve resolution reliability.
4

Check existing contacts

Use the Get All Contacts endpoint to see which contacts are already known to your instance and their LID mappings.
5

Retry later

If the error is temporary (network issues or WhatsApp service disruption), wait a few minutes and retry. Hypersender’s Queued Requests feature can help with automatic retries.

​
Working with LIDs in Your Integration

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.
If you need to retrieve the LID for a known phone number or find the phone number for a known LID, use these endpoints:

What is chatId?

Learn more about WhatsApp chat identifiers, including @c.us and @lid formats.