שגיאות של API v2

כל שגיאה של API v2 מגיעה עם קוד סטטוס HTTP אמיתי ובאותו מבנה JSON. הדף הזה מפרט כל code, מה הוא אומר ומה לעשות. כל תגובת שגיאה מקשרת ב-docs לקוד שלה כאן.

אובייקט השגיאה#

{
  "error": {
    "code": "not_cancellable",
    "message": "Only a waiting message can be cancelled.",
    "field": null,
    "docs": "https://wbiztool.com/docs/api/v2/errors/#not_cancellable",
    "request_id": "req_4f1c2a9b8e7d6c5b4a392817",
    "status": "sent"
  }
}

חלק מהקודים מוסיפים פרטים משלהם, כמו status, ‏count, ‏used או limit; הם מפורטים ליד הקוד. לתגובה עם HTTP 401 יש גם כותרת WWW-Authenticate: Bearer realm="wbiztool", ולתגובות עם 429 (ול-409 idempotency_in_progress) יש Retry-After.

בקצרה: 4xx פירושו שצריך לשנות את הבקשה (או, ב-409 וב-429, לחכות); ניסיון חוזר בלי שינוי יחזיר אותה תגובה. ‏5xx פירושו תקלה אצלנו; נסו שוב מאוחר יותר, עם אותו Idempotency-Key.

אימות ומגבלות#

api_v2_not_enabled#

HTTP 403. ‏API v2 לא זמין בסביבת העבודה הזו. אם אתם רואים את זה, צרו איתנו קשר.

מה לעשות: בינתיים המשיכו להשתמש ב-API v1. הכרטיס מפתחות API v2 בדף הגדרות ← מפתחות API מראה מתי הוא נפתח עבורכם.

missing_api_key#

HTTP 401. בבקשה אין כותרת Authorization: Bearer …, או שהיא ריקה או משתמשת בשיטה אחרת.

מה לעשות: שלחו Authorization: Bearer wbz_live_… (או wbz_test_…) בכל בקשה. ראו מפתחות.

invalid_api_key#

HTTP 401. המפתח אינו מפתח v2 של WbizTool: הוא הוקלד בטעות, נחתך, או שלא אנחנו יצרנו אותו.

מה לעשות: העתיקו את המפתח שוב, בלי רווחים או מירכאות. אי אפשר להציג מפתח שוב אחרי שהוא נוצר; אם איבדתם אותו, צרו מפתח חדש בדף הגדרות ← מפתחות API.

v1_key_on_v2#

HTTP 401. המפתח הוא מפתח של API v1 (40 תווים, ספרות והאותיות a עד f). מפתחות v1 עובדים רק ב-/api/v1/.

מה לעשות: צרו מפתח v2 בכרטיס מפתחות API v2 בדף הגדרות ← מפתחות API, או קראו ל-API v1.

api_key_revoked#

HTTP 401. התוקף של המפתח בוטל בדף הגדרות ← מפתחות API, או שסביבת העבודה שלו נמחקה או הושבתה.

מה לעשות: השתמשו במפתח אחר, או בקשו מאחד הבעלים של סביבת העבודה ליצור מפתח חדש.

api_key_expired#

HTTP 401. תאריך התפוגה של המפתח עבר.

מה לעשות: בקשו מאחד הבעלים של סביבת העבודה ליצור מפתח חדש, והחליפו בו את הישן באפליקציה שלכם.

too_many_auth_failures#

HTTP 429. ביותר מ-30 בקשות בדקה מכתובת ה-IP שלכם היה מפתח שגוי. ‏Retry-After הוא 60.

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

demo_account#

HTTP 403. סביבת עבודה של הדגמה לא יכולה להשתמש ב-API.

מה לעשות: הירשמו לחשבון משלכם וצרו בו מפתח.

missing_scope#

HTTP 403. למפתח אין את ההרשאה שהבקשה הזו דורשת. ‏required_scope בשגיאה מציין איזו, למשל messages:send.

מה לעשות: צרו מפתח עם ההרשאה הזו (אי אפשר להוסיף הרשאות למפתח קיים). ראו הרשאות.

rate_limited#

HTTP 429. המפתח שלח יותר מ-60 בקשות בדקה הזו, או יותר מ-10,000 היום (UTC).

מה לעשות: חכו את מספר השניות שב-Retry-After, ואז נסו שוב. פזרו את הבקשות, השתמשו ב-POST /messages/batch לנמענים רבים, וב-Webhooks במקום polling. ראו מגבלות קצב.

בקשה#

not_found#

HTTP 404. אין כלום בכתובת הזו: הנתיב הוקלד בטעות, או שאינו נתיב של API v2.

מה לעשות: השוו את הנתיב לתיעוד, למשל /api/v2/messages, ולא /api/v2/message.

invalid_json#

HTTP 400. הגוף אינו JSON תקין, לרוב בגלל פסיק בסוף או ירידת שורה לא מוברחת (unescaped) ב-text.

מה לעשות: בדקו את ה-JSON, וכתבו שורות חדשות במחרוזות כ-\n. תנו לספריית ה-HTTP שלכם לבנות את הגוף (json= ב-requests של Python, ‏JSON.stringify ב-JavaScript).

unsupported_content_type#

HTTP 415. הגוף לא נשלח בצורה שה-endpoint הזה מקבל: כל ה-endpoints מקבלים application/json, חוץ מ-POST /media, שמקבל multipart/form-data.

מה לעשות: הגדירו Content-Type: application/json ושלחו JSON, או שלחו את ההעלאה כ-multipart עם השדה file.

method_not_allowed#

HTTP 405. הנתיב קיים, אבל לא עם השיטה הזו, למשל PUT /messages/9817263.

מה לעשות: השתמשו בשיטה שמופיעה בתיעוד. שינוי של תזכורת הוא PATCH; ביטול של הודעה הוא DELETE.

request_too_large#

HTTP 413. גוף הבקשה גדול מדי.

מה לעשות: שלחו פחות בבקשה אחת, למשל פצלו רשימה ארוכה לכמה שליחות מרובות.

validation_failed#

HTTP 400. לבקשה אין את המבנה הנכון: שדה חובה חסר, לערך יש סוג שגוי או שהוא ארוך מדי, שדה לא מוכר, או ש-limit אינו בין 1 ל-100. ‏field מציין את הבעיה הראשונה ו-message מסביר אותה; ‏errors מפרט את השאר.

מה לעשות: תקנו את השדה שמצוין ב-field. שמות השדות הם ב-snake_case, ושדות לא מוכרים נדחים, לכן חפשו שגיאות הקלדה כמו txt או phone_number.

invalid_cursor#

HTTP 400. ה-cursor פגום, או שנוצר למסננים שונים מאלה שיש בבקשה הזו.

מה לעשות: שלחו בדיוק את ה-next_cursor שקיבלתם, עם אותם מסננים כמו בדף הראשון. כדי לשנות את המסננים, התחילו מחדש בלי cursor.

invalid_idempotency_key#

HTTP 400. הכותרת Idempotency-Key ריקה, ארוכה מ-255 תווים, או מכילה תווים שאי אפשר להדפיס.

מה לעשות: השתמשו ב-UUID או במחרוזת קצרה אחרת של אותיות, ספרות ומקפים.

idempotency_key_reused#

HTTP 422. ה-Idempotency-Key הזה כבר שימש ב-24 השעות האחרונות עם בקשה אחרת: שיטה, נתיב או גוף אחרים.

מה לעשות: השתמשו במפתח חדש לכל בקשה חדשה, והשתמשו שוב במפתח רק כדי לנסות שוב בדיוק את אותה בקשה. ראו Idempotency-Key.

idempotency_in_progress#

HTTP 409. הבקשה הראשונה עם ה-Idempotency-Key הזה עדיין בטיפול. ‏Retry-After הוא 1.

מה לעשות: חכו שנייה ושלחו שוב את אותה בקשה: תקבלו את התגובה של הבקשה הראשונה.

internal_error#

HTTP 500. משהו השתבש אצלנו. אנחנו מקבלים על כך התראה.

מה לעשות: נסו שוב מאוחר יותר עם אותו Idempotency-Key, כדי שהעבודה לא תתבצע פעמיים. אם זה ממשיך לקרות, צרו איתנו קשר עם ה-request_id.

הודעות#

text_required#

HTTP 400. בהודעה אין text ואין media, או שהטקסט מכיל רק רווחים. בתזכורת, ‏text הוא חובה.

מה לעשות: שלחו text, ‏media או את שניהם.

text_too_long#

HTTP 400. ‏text ארוך מ-3,000 תווים.

מה לעשות: קצרו אותו, או פצלו אותו לכמה הודעות.

too_many_recipients#

HTTP 400. בשליחה מרובה יש יותר מ-1,000 נמענים ב-to.

מה לעשות: פצלו את הרשימה לשליחות מרובות של עד 1,000, כל אחת עם Idempotency-Key משלה.

invalid_datetime#

HTTP 400. זמן (send_at, ‏expires_at, ‏since, ‏until) אינו ISO 8601 עם ההיסט שלו.

מה לעשות: כתבו אותו כמו 2026-10-20T09:30:00+05:30 או 2026-10-20T04:00:00Z. זמן בלי היסט, כמו 2026-10-20 09:30, נדחה כי הוא לא חד-משמעי. במחרוזת שאילתה, כתבו את + כ-%2B.

invalid_phone#

HTTP 422. מספר טלפון (to.phone, או phone בחיבור מספר) אינו מספר תקין בפורמט בינלאומי עם +.

מה לעשות: כתבו אותו עם + וקידומת המדינה, למשל ‎+919876543210. רווחים ומקפים בסדר; 0 מוביל במקום קידומת המדינה לא.

invalid_username#

HTTP 422. ‏to.username אינו שם משתמש של Telegram.

מה לעשות: כתבו ‎@name, קישור t.me/name או tg: ומזהה משתמש. ראו נמענים.

username_needs_telegram#

HTTP 422. אפשר לשלוח לשם משתמש של Telegram רק מחשבון Telegram, ו-from הוא מספר WhatsApp (או, בלי from, אין מחובר בדיוק חשבון Telegram אחד).

מה לעשות: הגדירו את from למזהה של חשבון Telegram, או שלחו למספר טלפון במקום זאת.

contact_not_found#

HTTP 422. אין בסביבת העבודה איש קשר עם ה-to.contact_id הזה.

מה לעשות: בדקו את המזהה (למשל ה-contact_id של הודעה קודמת), או שלחו ל-to.phone במקום זאת.

media_not_found#

HTTP 422 כששולחים הודעה או יוצרים תזכורת עם media.media_id; HTTP 404 ב-GET או DELETE /media/{id}. אין קובץ עם המזהה הזה בספריית המדיה של סביבת העבודה, או שהוא נמחק.

מה לעשות: בדקו את המזהה עם רשימת קבצים, או העלו את הקובץ שוב.

invalid_media_url#

HTTP 422. ‏media.url אינו קישור http או https ציבורי: הוא פגום, או שהוא מפנה לכתובת פרטית או מקומית.

מה לעשות: השתמשו בקישור שכל אחד באינטרנט יכול לפתוח, או העלו את הקובץ ושלחו אותו לפי media_id.

time_in_past#

HTTP 422. המועד של send_at או של expires_at כבר עבר.

מה לעשות: בדקו את הזמן ואת ההיסט שלו. כדי לשלוח עכשיו, השמיטו את send_at.

number_not_found#

HTTP 422 כש-from (או number_id בחיבור) אינו מספר של סביבת העבודה הזו; HTTP 404 ב-GET /numbers/{id}, גם כשהמפתח לא רשאי להשתמש במספר הזה.

מה לעשות: קחו את ה-id הנכון מרשימת מספרים.

from_required#

HTTP 422. ‏from חסר, ובסביבת העבודה אין מספר מחובר, או שיש יותר מאחד, כך שלא ברור איזה מהם צריך לשלוח. (במפתח שמוגבל לחלק מהמספרים: המספר המחובר היחיד אינו אחד מהמספרים שלו.)

מה לעשות: שלחו from עם ה-id של המספר שממנו שולחים.

number_not_allowed#

HTTP 403. המפתח מוגבל לחלק מהמספרים, והבקשה הזו צריכה מספר אחר: from הוא מספר אחר, תזכורת לא מציינת אחד מהמספרים שלו, בקשת חיבור מוסיפה מספר או מציינת מספר אחר, או שהבקשה מנהלת endpoints של Webhooks.

מה לעשות: השתמשו באחד מהמספרים של המפתח (number_ids ב-GET /me), או במפתח שאינו מוגבל.

no_credits#

HTTP 402. לא נותרו לסביבת העבודה הודעות בתוכנית. בשליחה מרובה, ‏requested ו-remaining מציינים כמה הודעות התבקשו וכמה נותרו.

מה לעשות: שלחו פחות הודעות, או קנו תוכנית או הודעות נוספות; תוכניות בתשלום שולחות הודעות ללא הגבלה. ראו כשההודעות נגמרות.

account_disabled#

HTTP 403. החשבון של הבעלים של סביבת העבודה מושבת, ולכן סביבת העבודה לא יכולה לשלוח.

מה לעשות: פנו לתמיכה.

number_daily_cap_reached#

HTTP 429. המספר השולח שלח 1,000 הודעות ב-24 השעות האחרונות (שימוש הוגן), או ששליחה מרובה לא נכנסת במה שנותר: requested ו-room מציינים כמה.

מה לעשות: שלחו את השאר מאוחר יותר, או ממספר אחר.

message_rejected#

HTTP 422. לא הצלחנו להכניס את ההודעה לתור; ‏message מסביר למה. שום דבר לא נשמר.

מה לעשות: תקנו את מה ש-message מתאר ושלחו שוב.

message_not_found#

HTTP 404. אין הודעה עם המזהה הזה עבור המפתח הזה: היא לא קיימת, שייכת לסביבת עבודה אחרת, או שנשלחה ממספר שהמפתח לא רשאי להשתמש בו. מפתח בדיקה רואה רק את הודעות הבדיקה שלו, ומפתח פעיל אף פעם לא רואה אותן.

מה לעשות: בדקו את המזהה, וודאו שאתם משתמשים באותו סוג מפתח (פעיל או בדיקה) שיצר את ההודעה.

not_cancellable#

HTTP 409. אפשר לבטל רק הודעה ממתינה (queued או scheduled), וההודעה הזו כבר לא ממתינה. ‏status בשגיאה מציין מה היא עכשיו, למשל sent או cancelled.

מה לעשות: אין מה לבטל. אי אפשר להחזיר הודעה שכבר נשלחה.

תזכורות#

invalid_cron#

HTTP 400. ‏schedule.cron אינו ביטוי cron בן 5 חלקים, או שהוא מתאר זמן שאף פעם לא מגיע (כמו 31 בפברואר).

מה לעשות: כתבו דקה, שעה, יום בחודש, חודש ויום בשבוע, למשל 0 9 * * 1 לימי שני ב-09:00. ראו לוח זמנים.

invalid_timezone#

HTTP 400. ‏schedule.timezone אינו שם של אזור זמן לפי IANA.

מה לעשות: השתמשו בשם כמו Asia/Kolkata, ‏Europe/London או America/New_York, ולא בקיצור כמו IST או בהיסט כמו ‎+05:30. ראו את מדריך אזורי הזמן.

number_not_connected#

HTTP 422. ה-from של התזכורת אינו מספר מחובר של סביבת העבודה הזו.

מה לעשות: חברו קודם את המספר, בחרו מספר מחובר, או השמיטו את from (null) כדי שכל מספר מחובר ישלח אותה.

reminder_not_found#

HTTP 404. אין תזכורת עם המזהה הזה: היא לא קיימת, נמחקה, או שהיא נשלחת ממספר שהמפתח לא רשאי להשתמש בו.

מה לעשות: בדקו את המזהה עם רשימת תזכורות.

מדיה#

file_too_large#

HTTP 413. הקובץ שהועלה גדול מ-64 MB.

מה לעשות: דחסו אותו או פצלו אותו; בסרטון, הורידו את הרזולוציה.

unsupported_file_type#

HTTP 415. אי אפשר לשלוח את סוג הקובץ ב-WhatsApp. הסוג נקרא מהסיומת שבסוף שם הקובץ.

מה לעשות: בדקו את הסוגים שאפשר להעלות, והשאירו את הסיומת בשם (price-list.pdf, ולא price-list).

storage_full#

HTTP 422. הקובץ לא נכנס בספריית המדיה של סביבת העבודה במסגרת התוכנית שלה. ‏used ו-limit מציינים כמה בשימוש וכמה מותר, בבתים.

מה לעשות: מחקו קבצים שאתם כבר לא צריכים, או עברו לתוכנית עם יותר נפח אחסון.

media_in_use#

HTTP 409. עדיין אי אפשר למחוק את הקובץ: משהו עדיין ישלח אותו (הודעה ממתינה, כולל הודעה של קמפיין, תזכורת פעילה או טריגר פעיל של Google Sheets). ‏count מציין כמה.

מה לעשות: בטלו או שנו אותם קודם, או חכו עד שההודעות הממתינות ייצאו.

upload_failed#

HTTP 502. לא הצלחנו לשמור את הקובץ אצלנו.

מה לעשות: נסו שוב, עם אותו Idempotency-Key.

בדיקת מספרים#

no_valid_numbers#

HTTP 422. אף אחת מהרשומות ב-numbers אינה מספר טלפון. ‏skipped מציין כמה רשומות היו.

מה לעשות: שלחו מספרים בפורמט בינלאומי עם +, אחד בכל רשומה, למשל ‎+919876543210.

too_many_numbers#

HTTP 422. בבדיקה יש יותר מספרים ממה שמותר בבדיקה אחת: יותר מ-10,000 רשומות בבקשה, או יותר מספרים ממה שהתוכנית מאפשרת לכל בדיקה. ‏count ו-limit מציינים כמה.

מה לעשות: פצלו את הרשימה לכמה בדיקות. ראו מגבלות התוכנית.

number_check_quota_reached#

HTTP 422. הבדיקה הייתה עוברת את מכסת בדיקת המספרים של התוכנית לתקופת החיוב הזו. ‏requested, ‏used ו-limit מציינים כמה.

מה לעשות: בדקו פחות מספרים, חכו לתקופת החיוב הבאה, או שדרגו את התוכנית.

number_check_not_found#

HTTP 404. אין בסביבת העבודה בדיקת מספרים עם המזהה הזה.

מה לעשות: בדקו את המזהה עם רשימת בדיקות.

מספרים#

plan_required#

HTTP 403. התוכנית של סביבת העבודה לא כוללת את מה שהבקשה הזו צריכה: את ה-API לקוד QR כדי לחבר מספר, תזכורות כדי ליצור, לשנות או לחדש תזכורת, או אימות מספרים כדי להתחיל בדיקת מספרים.

מה לעשות: בעלים יכולים לשדרג בדף מחירים. קריאה של מה שכבר קיים עובדת בכל תוכנית.

number_limit_reached#

HTTP 403. אין בתוכנית מקום למספר נוסף.

מה לעשות: חברו מחדש מספר קיים עם number_id, הסירו מספר שאתם כבר לא משתמשים בו, או שדרגו את התוכנית.

already_connected#

HTTP 409. המספר כבר מחובר.

מה לעשות: אין מה לעשות: אפשר לשלוח ממנו. בדקו עם קבלת מספר.

connect_in_progress#

HTTP 409. המספר הזה מתחבר ממש עכשיו. ‏number_id בשגיאה מציין איזה.

מה לעשות: בצעו polling ל-GET /numbers/{id} של המספר הזה במקום לבקש שוב. אחרי 10 דקות בלי סריקה, אפשר לבקש שוב.

Webhooks#

invalid_webhook_url#

HTTP 422. ‏url אינו כתובת https:// ציבורית: הוא http://, פגום, או מפנה לכתובת פרטית או מקומית.

מה לעשות: השתמשו בכתובת https:// שהשרת שלכם עונה בה מהאינטרנט. לבדיקה במחשב שלכם, השתמשו בשירות tunnel שנותן לכם כתובת https:// ציבורית.

webhook_limit_reached#

HTTP 403. בסביבת העבודה כבר יש 5 endpoints של Webhooks.

מה לעשות: הסירו endpoint שאתם כבר לא משתמשים בו. ‏endpoint אחד יכול לקבל את כל סוגי האירועים.

webhook_not_found#

HTTP 404. אין endpoint של Webhook עם המזהה הזה: הוא לא קיים או שהוסר. גם בדיקה או החלפת סוד של endpoint שהפסיק מחזירות את השגיאה הזו; קריאה שלו מציגה active: false.

מה לעשות: בדקו את המזהה עם רשימת endpoints. אם הוא הפסיק, הוסיפו אותו שוב.

מצב בדיקה#

test_mode_unsupported#

HTTP 403. מפתח בדיקה (wbz_test_…) יכול לשלוח, לקרוא ולבטל הודעות בדיקה ולקרוא את שאר סביבת העבודה, אבל לא לשנות שום דבר אחר: לחבר מספר, ליצור, לשנות או למחוק תזכורות, להעלות או למחוק מדיה, להתחיל בדיקת מספרים או לנהל endpoints של Webhooks. גם המסנן status של GET /messages לא נתמך במפתחות בדיקה.

מה לעשות: השתמשו במפתח פעיל (wbz_live_…) לבקשות האלה. ראו מצב בדיקה.