שגיאות ומגבלות קצב
כל שגיאה מוחזרת באותו מבנה:
{ "error": { "code": "insufficient_credits", "message": "Not enough credits. Top up your balance and try again.", "details": { "available": 12, "required": 40 } } }הסתמכו על code (יציב), לא על message (עשוי להשתנות).
| HTTP | code | משמעות | מה לעשות |
|---|---|---|---|
| 400 | validation_error | גוף/פרמטר לא תקין; details מפרט שדות | תקנו את הבקשה. שדות לא מוכרים נדחים |
| 400 | idempotency_key_required | חסר Idempotency-Key בשליחה | הוסיפו UUID ייחודי לכל שליחה לוגית |
| 401 | unauthorized | מפתח חסר, שגוי, פג או בוטל | בדקו את המפתח |
| 402 | insufficient_credits | אין מספיק קרדיטים | רכשו חבילה בפורטל |
| 403 | insufficient_scope | למפתח אין הרשאה לפעולה | צרו מפתח עם ה-scope המתאים |
| 403 | sender_not_verified | השולח לא מאומת בחשבון | אמתו את השולח ב-/senders |
| 403 | forbidden / org_suspended | אין גישה / החשבון מושעה | פנו לתמיכה |
| 404 | not_found | המשאב לא קיים (או שייך לחשבון אחר) | — |
| 409 | idempotency_conflict | אותו מפתח עם בקשה שונה, או שהבקשה המקורית עדיין בעיבוד | השתמשו במפתח חדש לבקשה חדשה |
| 422 | invalid_destination | אף יעד לא תקין; details.rejected | בדקו את המספרים |
| 429 | rate_limited / otp_rate_limited / daily_limit_exceeded | חריגה ממגבלה | המתינו retry_after שניות |
| 500/503 | internal_error / service_unavailable | תקלה זמנית | נסו שוב עם אותו Idempotency-Key |
סיבות כישלון מסירה (reason)
undeliverable, network_failure, expired, kosher_phone (מספר כשר שחסום ל-SMS), send_window (אין הרשאה לשליחה בשעה זו), blocked (הנמען חסם הודעות — נוסף אוטומטית לרשימה השחורה), invalid_content, no_coverage, rejected, cancelled, temporary_unavailable, internal_error.
סיבות דחייה בתשובת שליחה (rejected[].reason): invalid_phone, international_not_allowed, blacklisted, recently_messaged, duplicate, body_too_long, empty_body.
מגבלות קצב
| סוג | מגבלה לכל מפתח |
|---|---|
| שליחה (POST) | 60 בקשות לדקה |
| קריאה (GET) | 600 בקשות לדקה |
| OTP לאותו טלפון | 3 ב-10 דקות, 10 בשעה |
כל תשובה כוללת X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset. ב-429 יש גם header Retry-After. לשליחה בנפח גבוה השתמשו ב-/messages/batch (עד 2,500 הודעות בבקשה) במקום בקשה לכל הודעה.
חשבון חדש מוגבל ל-500 הודעות ביום עד לאימות פרטי העסק.