שגיאות API נפוצות ב-OKX ורשימת אבחון: תקן לפי הטבלה הזו

מי שכותב סקריפטים אלגוריתמיים, בתשעה מתוך עשרה מקרים לא נתקע באסטרטגיה אלא בשורת שגיאה אדומה: הסקריפט רץ, הטרמינל מקפיץ שרשרת של code ואנגלית שלא מובנים, ובן אדם נתקע. החדשות הטובות: לשגיאות ה-API של OKX יש רק כמה דגמים תכופים, וברגע שמבינים איך כל אחת נראית ולאיזו סיבה היא מתאימה, האבחון הופך הרבה יותר מהיר.

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

קודם תלמד לקרוא את השגיאה: code + msg

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

• קוד סטטוס HTTP: השכבה הגסה ביותר, למשל 401 (בעיית אימות), 429 (יותר מדי בקשות), 400 (הבעיה בבקשה עצמה).
• code: קוד שגיאה מספרי של OKX עצמה, שמצביע בדיוק הרב ביותר על סוג הבעיה. זה הבסיס העיקרי לאבחון שלך.
• msg: הסבר מילולי שעוזר לאשר את הכיוון, ולפעמים מצביע ישירות על השדה שנכשל.

אם אתה משתמש ב-ccxt, היא עוטפת את השגיאות הגולמיות האלה לסוגי חריגות קריאים יותר: בעיית אימות זורקת AuthenticationError, מגבלת קצב זורקת RateLimitExceeded, וחוסר יתרה זורק InsufficientFunds. מידע החריגה נושא בדרך כלל גם את ה-code וה-msg המקוריים של OKX. הרגל טוב הוא להדפיס אותם בבירור עם try/except:

import ccxt

okx = ccxt.okx({
    'apiKey':   'ה_apiKey_שלך',
    'secret':   'ה_secret_שלך',
    'password': 'ה_Passphrase_שלך',
    'enableRateLimit': True,
})

try:
    balance = okx.fetch_balance()
    print('USDT זמין:', balance['USDT']['free'])
except ccxt.AuthenticationError as e:
    print('כשל אימות, בדוק את שלושת האישורים ואת שעון המערכת:', e)
except ccxt.RateLimitExceeded as e:
    print('הגעת למגבלת קצב, האט את הבקשות:', e)
except ccxt.BaseError as e:
    print('שגיאה אחרת, בדוק את ה-code/msg המקוריים:', e)

רשום לעצמך את שרשרת ה-code וה-msg מהחריגה כמו שהיא, השווה לטבלה שלמטה, וברוב המקרים תאתר לאיזו קטגוריית בעיה זה שייך.

טבלת השגיאות התכופות

הטבלה הבאה מכסה את השגיאות שמתחילים נתקלים בהן הכי הרבה. קודי השגיאה הם לפי מה שמפורסם בתיעוד הנוכחי של OKX API v5 (OKX משנה מדי פעם ערכי קוד, ואם לא תואם — לך לפי טקסט ה-msg והתיעוד הרשמי), והעיקר הוא להתאים בין "סיבה ← איך לתקן".

אבחון ותיקון, שורה אחר שורה

הטבלה נותנת כיוון, הסעיף הזה נותן פרטים. בחר את השורה שנתקלת בה וקרא הלאה.

אימות (Invalid sign / API key לא תקין / Passphrase שגוי)

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

• קודם בדוק את ה-Passphrase. השדה password ב-ccxt חייב להיות מולא עם ה-Passphrase שהגדרת בעת יצירת המפתח — לא סיסמת ההתחברות, וגם לא ה-secret. זה לבדו תופס יותר ממחצית מכשלי האימות.
• אחר כך בדוק אם ה-apiKey / secret הועתקו שגוי. נפוץ שבהדבקה נוספו רווחים בתחילה/בסוף, או נחסרו תו או שניים. העתקה מחדש מהלוח היא הבטוחה ביותר.
• בנוסף בדוק את שעון המערכת. שעון לא מדויק גורם לחותמת זמן פגה, וזה מתבטא גם הוא ככשל אימות. הדלק NTP לכוונון.

אין הרשאה

הסימפטום הטיפוסי הוא "אפשר לבדוק יתרה, אי אפשר להזין". בדיקת יתרה עוברת בהרשאת קריאה, הזמנה עוברת בהרשאת מסחר, ושתיהן מאושרות בנפרד. חזור לניהול ה-API בלוח של OKX, מצא את המפתח הזה והוסף לו 'מסחר', בלי צורך ביצירה מחדש. אם מתוך הרגל סימנת גם משיכה — אל תשאיר אותה; למפתח שמריץ אלגו לעולם אל תפתח הרשאת משיכה.

יתרה לא מספיקה

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

symbol / דיוק

צמד ספוט ב-ccxt הוא באופן אחיד אותיות גדולות/אותיות גדולות עם קו נטוי קדמי, למשל BTC/USDT. כתיבה כ-BTCUSDT, אותיות קטנות, או פורמט חוזים — כולן יחזירו שגיאה. אם הכמות קטנה מדי או הדיוק שגוי, השתמש ב-load_markets() כדי לבדוק את הכמות המינימלית והדיוק של הצמד הזה, ומלא לפי הנדרש. יש לנו דוגמת הזמנה מלאה במבוא המעשי ל-API.

מגבלת קצב ו-retry עם נסיגה

מגבלת קצב (50011 / Too Many Requests) היא הקטגוריה שמשתמשי סקריפט נתקלים בה הכי הרבה, ושהכי כדאי למנוע מראש. היא לא אומרת שעשית משהו לא בסדר, אלא שהבקשות צפופות מדי והפעילו את ההגנה של הבורסה. הטיפול בה בשתי שכבות:

שכבה ראשונה: הדלק את מגביל הקצב המובנה של ccxt. הוסף באתחול 'enableRateLimit': True, ו-ccxt תשתול אוטומטית מרווחים סבירים בין הבקשות. ברוב המקרים השלב הזה מספיק:

okx = ccxt.okx({
    'apiKey':   'ה_apiKey_שלך',
    'secret':   'ה_secret_שלך',
    'password': 'ה_Passphrase_שלך',
    'enableRateLimit': True,   # מגביל קצב אוטומטי, הדלק קודם
})

שכבה שנייה: הוסף retry עם נסיגה מעריכית. אם האסטרטגיה שלך באמת מבצעת בקשות צפופות ברגעים מסוימים (למשל סורקת הרבה צמדים בו-זמנית), מגביל הקצב האוטומטי לבדו עדיין עלול להיתקל מדי פעם. אז עטוף את הבקשות הקריטיות בשכבת retry: נתקלת פעם, חכה שנייה ונסה שוב; שוב, חכה 2 ואז 4 שניות, האריך בהדרגה, ואחרי מספיק כשלונות — ויתר עם שגיאה.

import ccxt, time

def with_retry(fn, max_tries=5):
    delay = 1
    for i in range(max_tries):
        try:
            return fn()
        except ccxt.RateLimitExceeded:
            print(f'מגבלת קצב, ניסיון {i+1}, מחכה {delay} שניות ומנסה שוב')
            time.sleep(delay)
            delay *= 2          # נסיגה מעריכית: 1 ← 2 ← 4 ← 8 ...
    raise RuntimeError('עדיין נתקל במגבלת קצב אחרי כמה ניסיונות, מוותר')

# שימוש: זרוק לתוכה את הקריאה שעלולה להיתקל במגבלת קצב
ticker = with_retry(lambda: okx.fetch_ticker('BTC/USDT'))
print(ticker['last'])

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

בדיקה: מהמורה שאנחנו נתקלנו בה

שאלות נפוצות

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