Skip to main content
When sending WhatsApp messages through Chirp, errors from Meta’s Cloud API are automatically mapped to Chirp’s standard error format. The original Meta error details are always preserved in the provider object so you have full context for debugging. For a general overview of the error format, see Errors.

​
Error Code Mapping

The following table shows how Meta error codes are mapped to Chirp error codes. When a Meta error does not have a corresponding Chirp code, the error response uses type and message only.
Meta CodeMeta TitleChirp CodeChirp Message
1API Unknownmeta_api_errorAn unknown error occurred with the Meta API.
2API Servicemeta_api_unavailableMeta API is temporarily unavailable. Please try again later.
368Policy Violationsaccount_restrictedYour account has been restricted for policy violations.
130472Experiment Participantmessage_undeliverableMessage was not delivered due to Meta’s engagement policies.
130497Country Restrictionaccount_restrictedMessaging to users in this country is restricted.
131000Unknown Errormeta_api_errorMessage failed to send due to an unknown Meta error.
131005Access Denied—Permission not granted or has been removed.
131008Missing Parameter—A required parameter is missing from the request.
131016Service Unavailablemeta_api_unavailableWhatsApp service is temporarily unavailable.
131021Same Sender/Recipient—Sender and recipient phone numbers cannot be the same.
131026Message Undeliverablemessage_undeliverableUnable to deliver message. The recipient may have blocked your number or is unavailable on WhatsApp.
131031Account Lockedaccount_restrictedAccount has been locked due to policy violation.
131037Display Name Not Approveddisplay_name_not_approvedPhone number display name is pending Meta approval.
131042Payment Issueaccount_restrictedThere is a billing issue with your Meta account.
131047Re-engagement Messageconversation_window_expiredMore than 24 hours since the recipient last replied. Send a template message to re-open the conversation.
131049Ecosystem Protectionmessage_undeliverableMeta chose not to deliver this message to maintain platform quality.
131051Unsupported Message Typeunsupported_message_typeThis message type is not supported by WhatsApp.
131052Media Download Error—Unable to download the media sent by the user.
131053Media Upload Error—Unable to upload the media for sending.
131057Maintenance Modemeta_api_unavailableBusiness account is in maintenance mode.
131215Groups Not Eligiblegroups_not_eligibleThis phone number is not eligible to access the Groups API.
132000Template Param Mismatchtemplate_parameter_mismatchTemplate parameter count doesn’t match the template definition.
132001Template Nonexistenttemplate_not_foundTemplate doesn’t exist in the specified language or hasn’t been approved.
132005Translated Text Too Long—Translated template text exceeds the maximum length.
132007Template Policy Violationtemplate_not_foundTemplate content violates WhatsApp policy and has been rejected.
132012Param Format Mismatchtemplate_parameter_mismatchTemplate variable parameters are incorrectly formatted.
135000Generic Errormeta_api_errorMessage failed to send due to an unknown Meta error.
Entries marked with -- in the Chirp Code column use type and message only. These errors do not need a specific code because they do not require programmatic branching in your application.

​
Understanding Meta Error Responses

When a Meta error occurs, the Chirp API response includes the full provider details:
Meta error response
{
  "error": {
    "type": "provider_error",
    "code": "message_undeliverable",
    "message": "Unable to deliver message. The recipient may have blocked your number or is unavailable on WhatsApp.",
    "doc_url": "https://docs.buildwithchirp.com/api_reference/error-codes#message_undeliverable",
    "provider": {
      "source": "meta",
      "code": 131026,
      "message": "Unable to deliver message",
      "fbtrace_id": "A9PT_GrZ5LIImkA8UdH--jZ"
    }
  }
}

​
The Provider Object

FieldDescription
sourceAlways "meta" for WhatsApp errors.
codeMeta’s numeric error code. Use this for detailed debugging and when referencing Meta’s own documentation.
messageMeta’s error message in their own words.
fbtrace_idA unique trace identifier generated by Meta for each request. Critical for support tickets.

​
Using fbtrace_id

The fbtrace_id is the most important field when you need to escalate an issue with Meta. It allows Meta’s support team to look up the exact request in their systems. When to save it:
  • Always log the fbtrace_id when a WhatsApp message fails
  • Store it alongside the message record in your database
  • Include it in any support tickets or bug reports
How to use it:
  1. Open a support case through Meta Business Help Center
  2. Include the fbtrace_id value in your report
  3. Meta can use this to trace the exact API call and diagnose the issue
Saving fbtrace_id
if (error.provider?.fbtrace_id) {
  await db.messages.update({
    where: { id: messageId },
    data: {
      metaTraceId: error.provider.fbtrace_id,
      failureReason: error.code,
    },
  });
}

​
Common Scenarios

​
24-Hour Window Expired (131047)

WhatsApp Business API has a 24-hour messaging window. After a user messages you, you have 24 hours to respond with free-form messages. After the window closes, you must use an approved template message to re-initiate the conversation. What happens:
  1. A customer sends you a message at 10:00 AM
  2. You can send free-form messages until 10:00 AM the next day
  3. After 10:00 AM the next day, free-form messages fail with conversation_window_expired
  4. You must send a template message to re-open the conversation
How to handle it:
Handling expired conversation window
async function sendMessage(to, text) {
  const response = await fetch("https://api.buildwithchirp.com/v1/whatsapp/messages", {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${apiKey}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ to, type: "text", text: { body: text } }),
  });

  if (!response.ok) {
    const { error } = await response.json();

    if (error.code === "conversation_window_expired") {
      // Fall back to a template message
      return sendTemplateMessage(to, "follow_up", {
        body: [{ type: "text", text }],
      });
    }

    throw new Error(error.message);
  }

  return response.json();
}
Track the last message timestamp from each customer so you can proactively switch to template messages before the window expires.

​
Account Restricted (368, 131031, 131042)

Account restrictions prevent you from sending messages. They can happen for several reasons:
Meta CodeReasonResolution
368Policy violationsReview and fix the policy violation in Meta Business Manager
130497Country restrictionMessaging to users in certain countries may be restricted
131031Account lockedYour account was locked; appeal through Meta Business Manager
131042Payment issueResolve the billing issue in your Meta account
Steps to resolve:
  1. Log in to Meta Business Manager
  2. Check for any policy violation notices or account quality warnings
  3. Review the WhatsApp Business Policy
  4. If your account was restricted in error, submit an appeal through Business Manager
  5. For billing issues, update your payment method in account settings
Account restrictions affect all messages from your WhatsApp Business Account, not just individual phone numbers. Resolve them as quickly as possible to avoid service disruption.

​
Template Issues (132000, 132001, 132005, 132007, 132012)

Template errors occur when sending template messages. They fall into two categories: Template does not exist (132001, 132007):
  • The template name is misspelled
  • The template was not approved in the requested language
  • The template was rejected by Meta for policy violations
Template parameter problems (132000, 132012):
  • Wrong number of variables provided
  • Variables in the wrong format
  • Missing required header or button parameters
Troubleshooting steps:
  1. Verify the template exists in your dashboard or via the Templates API
  2. Check that the template status is “approved”
  3. Confirm the language code matches the approved template language
  4. Count the variables in your template body and verify you are providing the exact same number
  5. Check that variable types match (text, currency, date-time)
Template error handling
const response = await fetch("https://api.buildwithchirp.com/v1/whatsapp/templates/send", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${apiKey}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    to: "+15559876543",
    template: {
      name: "order_confirmation",
      language: { code: "en_US" },
      components: [
        {
          type: "body",
          parameters: [
            { type: "text", text: "John" },
            { type: "text", text: "#12345" },
            { type: "text", text: "$99.99" },
          ],
        },
      ],
    },
  }),
});

if (!response.ok) {
  const { error } = await response.json();

  if (error.code === "template_not_found") {
    console.error("Template does not exist or is not approved.");
    // Check template status in dashboard
  }

  if (error.code === "template_parameter_mismatch") {
    console.error("Variable count or format does not match template definition.");
    // Verify template parameters
  }
}