# שגיאות

## מבנה תשובת שגיאה

כל שגיאה מוחזרת כ-JSON באותו מבנה:

```json
{
  "error": "Lead not found or access denied",
  "details": "...",
  "status": 404
}
```

| שדה | תמיד? | תיאור |
|---|---|---|
| `error` | כן | תיאור קצר וקבוע של השגיאה (באנגלית). אפשר להסתמך עליו בלוגים ובהתראות. |
| `status` | כן | קוד הסטטוס של HTTP, זהה לסטטוס של התגובה. |
| `details` | לא | הסבר נוסף, כשיש כזה. |
| `reason` | ב-401 וב-503, ובחלק מ-403 | ב-401, הסיבה לכשל האימות; ב-503, `auth_service_error`. ב-403, `subscription_inactive` כשהמנוי של הארגון לא פעיל, או `note_locked` כשהערה נעולה ניתנת לשינוי רק על ידי יוצרה או מפתח מנהל. ראו [אימות והרשאות](https://docs.banta.co.il/he/guides/authentication.md). |
| `retry_after` | ב-429 | מועד פתיחת חלון הבקשות הבא (ISO 8601). הכותרת `Retry-After` מכילה את אותה המתנה בשניות. |
| `code` | לפעמים | קוד שגיאת מסד נתונים, כשהוא בטוח לחשיפה: ב-400 (למשל `23514` לסטטוס שלא הוגדר בארגון), ב-409 (`23505`, ערך כפול) וב-500. |

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

## קודי סטטוס

| סטטוס | משמעות | מה לעשות |
|---|---|---|
| `400 Bad Request` | גוף לא תקין (JSON שבור או לא אובייקט), שדה חובה חסר, ערך לא חוקי (למשל סטטוס לא מוכר, מזהה בפורמט שגוי, או מזהה של ארגון אחר), או עדכון בלי אף שדה שניתן לעדכן | תקנו את הבקשה. אל תנסו שוב כמו שהיא. |
| `401 Unauthorized` | מפתח API חסר, לא תקין, שפג תוקפו או שבוטל | בדקו את `reason` |
| `403 Forbidden` | למפתח אין הרשאה לפעולה על המשאב | הוסיפו הרשאה למפתח |
| `404 Not Found` | הרשומה לא קיימת, נמחקה או שייכת לארגון אחר, או שהנתיב לא קיים (למשל סגמנט עודף) | בדקו את המזהה ואת הנתיב |
| `405 Method Not Allowed` | שיטת ה-HTTP לא נתמכת בנתיב הזה, למשל `POST /tasks/{id}` (הוא לא יוצר משימה). הכותרת `Allow` מפרטת את השיטות הנתמכות. | השתמשו באחת השיטות שב-`Allow` |
| `409 Conflict` | הפעולה מתנגשת במצב הקיים: קישור שכבר קיים, הערה נעולה, תשלום שבוטל, או ערך ייחודי כפול (כמו מספר זהות) | קראו את הרשומה הקיימת והחליטו מה לעשות |
| `429 Too Many Requests` | חריגה ממגבלת הקצב | המתינו עד `retry_after`. ראו [מגבלות קצב](https://docs.banta.co.il/he/guides/rate-limits.md). |
| `500 Internal Server Error` | תקלה בצד של banta | נסו שוב עם המתנה הולכת וגדלה. אם זה חוזר, פנו לתמיכה. |
| `503 Service Unavailable` | תקלה זמנית בשירות האימות (`reason: auth_service_error`). המפתח לא נדחה. | נסו שוב בעוד כמה שניות, עם המתנה הולכת וגדלה |

> ה-API מחזיר `404` גם על רשומה שקיימת בארגון אחר. כך אי אפשר לגלות אם מזהה מסוים קיים במערכת.

## הצלחה חלקית

`POST /mortgage-files` בודק את כל מה שנשלח, כולל `borrowers`, לפני שהוא יוצר משהו - פריט לא תקין מחזיר `400` ושום דבר לא נשמר. אחרי שהתיק נשמר, הרשומות המקוננות שלו (לווים, הכנסות, חשבונות בנק, התחייבויות) נשמרות אחת אחרי השנייה. אם אחת מהן נכשלת בצד מסד הנתונים, הקריאה עדיין מחזירה `201` עם התיק ומערך `child_errors`, למשל `["borrower[1]: 23505"]`.

אל תשלחו שוב את ה-`POST` - כך ייווצר תיק שני. השלימו את החסר בתיק הקיים עם `POST /mortgage-files/{id}/borrowers` או `PATCH /mortgage-files/{id}`. ב-`PUT`/`PATCH`, `incomes`, `bank_accounts` ו-`obligations` הם `null` בתגובה כשלא שלחתם אותם, ולא כשהם ריקים.

## ניסיונות חוזרים

- **כדאי לנסות שוב:** `429` (אחרי ההמתנה שב-`Retry-After`), `500`, `503`, ושגיאות רשת או timeout. השתמשו בהמתנה מעריכית (למשל 1, 2, 4, 8 שניות) עם מעט אקראיות.
- **אין טעם לנסות שוב בלי לשנות משהו:** `400`, `401`, `403`, `404`, `405`, `409`.
- **זהירות עם `POST` אחרי timeout:** ייתכן שהבקשה הראשונה הצליחה. ה-API לא תומך כרגע ב-idempotency keys, ולכן לפני שליחה חוזרת של יצירה כדאי לבדוק עם `search` אם הרשומה כבר נוצרה.

---

חלק מתיעוד ה-API של banta. אינדקס מלא: https://docs.banta.co.il/he/llms.txt