שגיאות
השגיאות חולקות מעטפת אחת (ראו את הסקירה). הסתעפו לפי code, רשמו ביומן את meta.request_id, והתייחסו ל-message כטקסט באנגלית שמיועד לבני אדם.
שגיאות לקוח
Section titled “שגיאות לקוח”| קוד | סטטוס | משמעות ומה לעשות |
|---|---|---|
validation_failed |
400 | שדה נכשל באימות. field מציין אותו; details מסביר. תקנו את השדה. |
bad_request |
400 | לא ניתן היה לקרוא את הבקשה כלל: JSON פגום, זרם Content-Encoding שבור, גוף שנקטע. אין שדה לתקן; בדקו את שכבת התעבורה. |
validation_error |
400 | X-Account-Id נשלחה לנקודת קצה שאוסרת אותה (/auth/login, /auth/refresh, /auth/swap-company, /auth/logout). |
cursor_expired |
400 | סמן העימוד ישן מ-24 שעות. התחילו את הרשימה מחדש. |
unauthenticated |
401 | אסימון חסר או לא תקין. רעננו את הסשן או בדקו את המפתח. |
invalid_signature |
401 | חתימת webhook לא אומתה. ראו Webhooks. |
forbidden |
403 | האסימון תקין אבל חסרה לו ההרשאה. |
account_context_mismatch |
403 | X-Account-Id אינה תואמת לחשבון של האסימון. התפיסה של הלקוח לגבי החברה הנוכחית סטתה; קראו אותה מחדש מהסשן. |
not_found |
404 | המשאב אינו קיים או שייך לחשבון או לאתר אחר. ה-API לעולם אינו מבחין בין השניים. |
conflict |
409 | התנגשות מצב: נעילה אופטימית, אילוץ ייחודיות, או פעולה שאינה מותרת במצב הנוכחי (למשל כתיבה לשיחה ממוזגת). |
idempotency_key_conflict |
409 | נעשה שימוש חוזר ב-Idempotency-Key עם גוף שונה. |
payload_too_large |
413 | הגוף חורג מהמגבלה של משפחת נקודות הקצה הזו. |
unsupported_media_type |
415 | Content-Type שגוי. |
unprocessable |
422 | JSON תקין, אבל כלל עסקי דחה אותו (למשל מועד הזמנה מחוץ לשעות הפעילות). |
storage_quota_exceeded |
422 | החשבון הגיע למגבלת האחסון של התוכנית. details נושא את used_bytes, quota_bytes ו-requested_bytes; פנו מקום או שדרגו. |
rate_limited |
429 | האטו. כבדו את Retry-After ואת details.retry_after_seconds. |
שגיאות שרת
Section titled “שגיאות שרת”| קוד | סטטוס | משמעות ומה לעשות |
|---|---|---|
internal_error |
500 | כשל לא צפוי. נסו שוב פעם אחת, ואז פנו לתמיכה עם request_id. |
upstream_unavailable |
502 | השער לא הצליח להגיע לשירות כלל. ניסיון חוזר קצר בדרך כלל מצליח. |
service_unavailable |
503 | תחזוקה מתוכננת או מפסק זרם פתוח. נסו שוב אחרי הזמן שבכותרת Retry-After. |
ai_vendor_out_of_funds |
503 | ספק ה-AI שלכם דחה את הקריאה מסיבות חיוב (402 או 429 של מכסה מהספק). טענו את החשבון אצל הספק; ניסיון חוזר לא יעזור. |
upstream_timeout |
504 | השירות לא ענה בזמן. נסו שוב כש-retry_after קיים. |
ניסיונות חוזרים
Section titled “ניסיונות חוזרים”נסו שוב 429, 502, 503, 504 וכשלי רשת עם השהיה מעריכית, ושלחו את אותו Idempotency-Key בניסיון החוזר כדי שכתיבה לעולם לא תוחל פעמיים. אל תנסו שוב 4xx מלבד 429.