WhatsApp Error Codes

{
  "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"
    }
  }
}

if (error.provider?.fbtrace_id) {
  await db.messages.update({
    where: { id: messageId },
    data: {
      metaTraceId: error.provider.fbtrace_id,
      failureReason: error.code,
    },
  });
}

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();
}

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
  }
}

{
  "error": {
    "type": "provider_error",
    "code": "account_restricted",
    "message": "Account has been locked due to policy violation.",
    "doc_url": "https://docs.buildwithchirp.com/api_reference/error-codes#account_restricted",
    "additional_info": [
      "Appeal via Business Manager."
    ],
    "provider": {
      "source": "meta",
      "code": 131031,
      "message": "Account has been locked",
      "fbtrace_id": "BxYZ_abc123def456",
      "health_status": {
        "can_send_message": "BLOCKED",
        "entities": [
          {
            "entity_type": "PHONE_NUMBER",
            "id": "852850827913949",
            "can_send_message": "BLOCKED",
            "errors": [
              {
                "error_code": 131031,
                "error_description": "Account has been locked",
                "possible_solution": "Appeal via Business Manager."
              }
            ]
          },
          {
            "entity_type": "WABA",
            "id": "1472866130489042",
            "can_send_message": "AVAILABLE"
          },
          {
            "entity_type": "BUSINESS",
            "id": "506914307656634",
            "can_send_message": "AVAILABLE"
          },
          {
            "entity_type": "APP",
            "id": "634974688087057",
            "can_send_message": "AVAILABLE"
          }
        ]
      }
    }
  }
}

async function handleWhatsAppError(error) {
  // Always-present fields
  console.error(`[${error.code}] ${error.message}`);

  // Enrichment is best-effort — always check for presence
  if (error.additional_info?.length) {
    console.error("Meta's suggested fix:");
    for (const hint of error.additional_info) {
      console.error(`  - ${hint}`);
    }
  }

  // Richer UI: show which entity is actually blocking
  const blockedEntity = error.provider?.health_status?.entities?.find(
    (e) => e.can_send_message === "BLOCKED",
  );
  if (blockedEntity) {
    await notifyOperator({
      entity: blockedEntity.entity_type,     // e.g. "PHONE_NUMBER"
      id: blockedEntity.id,
      cause: blockedEntity.errors?.[0]?.error_description,
      solution: blockedEntity.errors?.[0]?.possible_solution,
    });
  }
}