# אין תוצאה או שגיאת API: איך להבדיל?

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

Source: https://www.roote.ai/he/guides/%D7%90%D7%99%D7%9F-%D7%AA%D7%95%D7%A6%D7%90%D7%94-%D7%90%D7%95-%D7%A9%D7%92%D7%99%D7%90%D7%AA-api-%D7%90%D7%99%D7%9A-%D7%9C%D7%94%D7%91%D7%93%D7%99%D7%9C/
Language: he
Author: ROOTE

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

ל-ROOTE, בדקו תחילה את תגובת HTTP ואז את המעמד העסקי, האוסף הצפוי והכיסוי. פעולה זו מונעת הצגת "אין שירותים" כאשר קריאה לשירותים נכשלה או "אין תחנות" לאחר חריגה ממועד ההמתנה.

## קריאת שלושת רמות התגובה

| רמה | לבדוק | מסקנה אפשרית |
| --- | --- | --- |
| תעבורה | חיבור, זמן תגובה ומעמד HTTP | האם הבקשה הצליחה? |
| חוזה | JSON תקין, גרסה ושדות צפויים | האם התגובה ניתנת לעיבוד? |
| תוצאה עסקית | סטטוס, אוספים, כיסוי, אזהרות ומטה | מה ידוע בתחום המבוקש? |

קוד HTTP 200 אינו מספיק לאישור חיפוש. התגובה עשויה לציין ביצוע חלקי או סטטוס שגיאה. לעומת זאת, 404 לנתיב אינו דרך תקינה לציון אוסף ריק: בדקו את כתובת ה-URL ואת החוזה.

## הבנת success, empty, partial ו-error

| סטטוס | טיפול מומלץ |
| --- | --- |
| success | הציגו את הישויות לאחר אימות וצרו את המגבלות |
| empty | הודיעו כי לא הוחזרו תוצאות לחיפוש זה |
| partial | הציגו מידע שימושי עם האזהרות שלו |
| error | הציגו את החיפוש כבלתי זמין; אל תסיקו היעדר מקומות |

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

## עץ החלטה לממשק שלכם

```
1. La requête a-t-elle abouti ?
   Non → indisponibilité réseau ou délai dépassé.
2. Le statut HTTP est-il acceptable selon le contrat ?
   Non → traiter le code et le message d'erreur.
3. Le JSON respecte-t-il le schéma attendu ?
   Non → réponse inexploitable, jamais "aucun résultat".
4. Le statut métier est-il error ?
   Oui → recherche indisponible.
5. Le statut est-il partial ou la couverture limitée ?
   Oui → résultats utilisables + avertissement.
6. La collection attendue est-elle vide ?
   Oui → aucun résultat retourné dans ce périmètre.
   Non → afficher les résultats et leurs limites.
```

## בדקו פרמטרים בסדר הנכון

בדקו תחילה קו רוחב וקו אורך, את הסדר ואת העיר שהתקבלה. אחר כך בדקו את יחידת הרדיוס ואת אוצר המילים של המסננים. ל-API של שירותים משתמשים ב-types=toilets; מפת URL משתמשת ב-modes=toilets. פרמטרים אלה שייכים לחוזים שונים.

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

[בניית חיפוש API סביב קואורדינטות GPS](https://www.roote.ai/he/guides/echapes-transports-qaroveka-imapi/)

## טיפול במקור לא זמין ללא אובדן האחרים

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

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

## התאמת הודעות והתאוששויות

| מצב | הודעה להתאמה בממשק שלכם | פעולה |
| --- | --- | --- |
| empty | אין תוצאה שהוחזרה באזור הזה עם מסננים אלה | שנו את האזור או את המסננים |
| partial | תוצאות מסוימות זמינות; החיפוש אינו שלם | הציגו את התוצאות ואת האזהרה |
| שגיאת אימות | החיפוש כולל פרמטר לא חוקי | תיקנו את הבקשה |
| אימות או הרשאות | גישה זו אינה מאפשרת חיפוש זה | בדקו את החשבון או את הטוקן |
| מגבלה או חוסר זמינות | החיפוש זמנית לא זמין | כבדו את הוראות ההתאוששות |

ל-429 עקבו אחר הוראות השירות ו-Retry-After אם יש. שגיאת 400 דורשת תיקון פרמטרים; חזרה על אותה בקשה לא תפתור. אל תהפכו 401 לקריאה אנונימית אוטומטית אם המשתמש סיפק טוקן.

[תיעוד שגיאות API של ROOTE](https://doc.roote.ai/roote-api/errors)

[מצב שירותי ROOTE](https://status.roote.ai/)

## בדקו את ארבעת המעמדות לפני פרסום

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

[יישום כללים אלה בעוזר AI](https://www.roote.ai/he/guides/%D7%90%D7%99%D7%9A-%D7%9C%D7%99%D7%A6%D7%95%D7%A8-%D7%A2%D7%95%D7%96%D7%A8-%D7%9E%D7%95%D7%91%D7%99%D7%99%D7%9C%D7%99%D7%95%D7%AA-%D7%9E%D7%A1%D7%91%D7%99%D7%91-%D7%9C%D7%9B%D7%AA%D7%95%D7%91%D7%AA/)

[הבנת פורמטים של נתוני תחבורה](https://www.roote.ai/he/guides/gtfs-gtfs-rt-ogbfs-mahem-havdalaim/)

## שאלות נפוצות

### האם רשימה ריקה מוכיחה היעדר שירותים?

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

### האם ניתן להציג תגובה חלקית?

כן, אם הישויות תקינות ושמורים האזהרות והמגבלות הנדרשות.

### האם יש צורך לחזור על כל שגיאה?

לא. תקנו שגיאות בפרמטרים או גישה; הגבילו התאוששויות לתקלות זמניות וכבדו את הוראות השירות.