מה אומרת שגיאה 131047 ב-WhatsApp Cloud API?

המשמעות היא שחלון השירות של 24 שעות נסגר. אחרי 24 שעות מההודעה הנכנסת האחרונה של הלקוח, טקסט חופשי נדחה ורק תבנית מאושרת נמסרת. זה כלל של הפלטפורמה, לא באג. החלון נפתח מחדש ברגע שהלקוח שולח הודעה נוספת.

למה ה-API של WhatsApp ממשיך להחזיר קוד 100 "Invalid parameter"?

קוד 100 הוא שגיאת הוולידציה הגנרית של Meta, ושדה ה-message שלו מעורפל בכוונה. הסיבה הספציפית נמצאת ב-error_user_title, ב-error_user_msg וב-error_data.details באותה תשובה. תעד את שלושת השדות האלה והסיבה האמיתית - בדרך כלל שם תבנית, שפה או מבנה פרמטרים - תתגלה מיד.

אילו שגיאות WhatsApp צריכות לעצור שליחה המונית במקום לנסות שוב?

131048 (חשד לספאם), 131056 (יותר מדי הודעות לאותו נמען), 80007 (מגבלת קצב של החשבון) ו-368 (חסימה זמנית עקב מדיניות). הן מעידות שהחשבון עצמו בסיכון. ניסיון חוזר בלולאה הוא דרך מוכרת להביא לחסימת חשבון WhatsApp Business, ולכן מנגנון השליחה צריך להשהות את הקמפיין אוטומטית כשאחת מהן מופיעה.

מה גורם לשגיאה 132001 כשהתבנית בבירור קיימת?

כמעט תמיד אי-התאמה בשפה. תבניות מאושרות לפי קוד שפה, כך שתבנית שאושרה כ-"he" תחזיר 132001 אם תשלח אותה כ-"en_US". הסיבה הנפוצה השנייה היא שהתבנית מאושרת ב-WhatsApp Business Account אחר מזה שאליו שייך מזהה מספר הטלפון שלך.

האם שגיאה 131026 היא משהו שאפשר לתקן בקוד?

לא. 131026 אומרת שההודעה לא ניתנת למסירה לאותו אדם ספציפי - אין לו חשבון WhatsApp, הוא חסם את המספר שלך, או שלא אישר את התנאים העדכניים. הטיפול הנכון הוא לסמן את המספר כלא-מסיר ולהפסיק לנסות, לא לשנות את הבקשה.

מה זה fbtrace_id והאם צריך אותו?

זה מזהה לכל בקשה ש-Meta מחזירה בשגיאות. אי אפשר להשתמש בו לבד, אבל התמיכה של Meta תבקש אותו, ובלעדיו פנייה על כשל אקראי בדרך כלל לא מתקדמת. שמור אותו עם כל שגיאה מתועדת.

קודי שגיאה ב-WhatsApp Cloud API

מדריך עבודה לשגיאות שבאמת פוגשים ב-WhatsApp Cloud API - מה אומרים קוד 100, 131047, 131048, 132001 ו-190, איפה Meta מסתירה את הסיבה האמיתית, ומה עושים עם כל אחת.

ה-WhatsApp Cloud API מחזיר שגיאות בפורמט אחיד של Graph API, אבל השדה שרוב המפתחים מתעדים - error.message - הוא בדרך כלל הכללי ביותר שיש. הסיבה האמיתית מוסתרת בשדות אחרים באותה תשובה. המדריך הזה הוא טבלת העבודה: מה כל קוד אומר, אילו קודים דורשים עצירה מיידית, ומה לשמור כדי שאפשר יהיה לנפות שגיאות אחרי שהן קרו.

מבנה השגיאה - ואיפה Meta מסתירה את הסיבה

כל כשל מגיע כ-JSON תחת המפתח error, עם השדות הבאים:

code - הקוד המספרי. זה מה שמנתבים לפיו.
error_subcode - תת-קוד, לא תמיד קיים.
message - טקסט כללי. עבור קוד 100 זה יהיה "Invalid parameter" ותו לא.
error_user_title ו-error_user_msg - כאן נמצאת הסיבה האמיתית, במיוחד בכשלי ולידציה של תבניות.
error_data.details - פירוט נוסף, לרוב הכי מדויק מכולם.
fbtrace_id - מזהה שצריך לצרף לכל פנייה לתמיכה של Meta.

המשמעות המעשית: אם המערכת שלך שומרת רק message, כל שגיאת תבנית תיראה זהה - "Invalid parameter" - ולא תדע אם הבעיה היא מספר משתנים שגוי, טקסט ארוך מדי או תבנית שהושהתה. שמור את כל השדות, ושרשר את error_user_title, error_user_msg ו-error_data.details להודעה אחת שמוצגת למפעיל.

אימות והרשאות

קוד	מה זה אומר ומה עושים
190	ה-Access Token פג תוקף או שגוי. הפתרון הוא טוקן של System User דרך Business Manager, לא טוקן זמני מ-Graph API Explorer.
131005	לטוקן חסרה ההרשאה `whatsapp_business_messaging`, או שה-System User לא משויך לנכסי ה-WABA ומספר הטלפון.
131042	בעיית תשלום ברמת ה-WABA. בלי אמצעי תשלום פעיל ב-Business Manager אי אפשר לשלוח תבניות בתשלום.

רישום המספר

קוד	מה זה אומר ומה עושים
131045	המספר לא רשום כראוי ב-Cloud API. יש להשלים רישום, כולל קוד PIN דו-שלבי.
133010	המספר לא רשום ב-Cloud API כלל. להשלים את שלב ה-API Setup לפני כל שליחה.

חלון 24 השעות

קוד	מה זה אומר ומה עושים
131047	חלון השירות של 24 שעות נסגר. אי אפשר לשלוח טקסט חופשי - רק תבנית מאושרת - עד שהלקוח ישלח הודעה חדשה. זו לא תקלה אלא כלל של הפלטפורמה, ועדיף לאכוף אותו בצד השרת לפני השליחה במקום לגלות אותו מהשגיאה.
131050	הנמען ביקש להפסיק לקבל הודעות שיווקיות מהמספר הזה. לסמן אותו כמסורב ולא לנסות שוב.
131049	Meta בחרה לא למסור את ההודעה בגלל מגבלות שיווק ברמת הנמען. אין מה לתקן בקוד.

קצב וספאם - הקודים שדורשים עצירה

ארבעת הקודים האלה שונים מכל השאר. הם לא באג בבקשה, אלא איתות שהחשבון בסכנה. מנגנון שליחה תקין צריך להשהות את הקמפיין אוטומטית ברגע שאחד מהם חוזר, ולא לנסות שוב בלולאה.

קוד	מה זה אומר ומה עושים
131048	השליחה נחסמה עקב חשד לספאם ודירוג איכות נמוך. להאט משמעותית ולשפר את התוכן.
131056	יותר מדי הודעות לאותו נמען בזמן קצר. להמתין לפני שליחה נוספת לאותו מספר.
80007	חריגה ממגבלת הקצב של חשבון ה-WhatsApp Business.
368	החשבון חסום זמנית עקב הפרת מדיניות. לבדוק ב-WhatsApp Manager - זה כבר לא עניין של קצב.

תבניות

קוד	מה זה אומר ומה עושים
132000	מספר ערכי הפרמטרים לא תואם למספר המשתנים בתבנית. תבנית עם שלושה משתנים דורשת בדיוק שלושה ערכים.
132001	התבנית לא קיימת או לא מאושרת בשפה שנבחרה. שים לב שאישור ב-`he` אינו אישור ב-`en_US`.
132005	הטקסט ארוך מדי אחרי הצבת הפרמטרים. יש לקצר את הערכים או את גוף התבנית.
132007	תוכן התבנית מפר את מדיניות WhatsApp.
132012	פורמט ערך הפרמטר לא תואם להגדרת התבנית.
132015	התבנית מושהית עקב דירוג איכות נמוך. אי אפשר לשלוח בה עד שתשוחרר.
132016	התבנית הושבתה לצמיתות. יש ליצור תבנית חדשה.

מסירה, מדיה ושגיאות כלליות

קוד	מה זה אומר ומה עושים
131026	לא ניתן למסור. לנמען אין WhatsApp, או שחסם אותך, או שלא אישר את התנאים החדשים. זו השגיאה הנפוצה ביותר ברשימות מספרים לא מנוקות.
131021	הנמען זהה למספר השולח. אי אפשר לשלוח לעצמך.
131009	ערך פרמטר לא תקין. לבדוק את מזהה מספר הטלפון ואת פורמט מספר הנמען.
131008	חסר פרמטר חובה בבקשה.
131051	סוג הודעה לא נתמך.
131052	כשל בהורדת המדיה מהקישור שסופק.
131053	כשל בהעלאת המדיה. לבדוק פורמט וגודל.
131000	שגיאה כללית של Meta. אפשר לנסות שוב מאוחר יותר.
131016	שירות Meta לא זמין כרגע.
131031	חשבון ה-WhatsApp Business ננעל. לבדוק ב-WhatsApp Manager.
130472	הנמען משתתף בניסוי של Meta ולא ניתן לשלוח לו הודעות שיווקיות.

מה לשמור בבסיס הנתונים

לכל הודעה יוצאת כדאי לשמור שורה עם wamid ייחודי ואובייקט שגיאה מלא. ה-wamid הוא גם מפתח הדדופליקציה: Meta שולחת עדכוני סטטוס דרך webhook, ולפעמים שולחת את אותו עדכון פעמיים. אינדקס ייחודי דליל על wamid פותר את זה בלי קוד נוסף.

שמירה של הודעת השגיאה המלאה מאפשרת להציג למפעיל, בתוך שיחת הצ'אט עצמה, למה בדיוק ההודעה לא נשלחה - במקום סימן קריאה אדום שלא אומר כלום.

קודי שגיאה ב-WhatsApp Cloud API: מה כל אחד באמת אומר

עיקרי הדברים