خطاها و پاسخ‌های ناموفق¶

مقدمه¶

این سند تمامی خطاهای ممکن در API را توضیح می‌دهد. هر خطا شامل کد وضعیت HTTP، پیام و راه‌حل است.

ساختار خطای استاندارد¶

فرمت¶

{
  "detail": [
    {
      "loc": ["body", "field_name"],
      "msg": "توضیح خطا",
      "type": "error_type",
      "ctx": {
        "limit_value": 100
      }
    }
  ]
}

توضیحات فیلدها¶

detail: آرایه‌ای از خطاها یا یک رشته ساده
loc: مکان خطا (body, query, path)
msg: پیام توضیحی
type: نوع خطا
ctx: اطلاعات اضافی (اختیاری)

خطاهای احراز هویت (401)¶

1. Not authenticated¶

کد: 401 Unauthorized

پاسخ:

{
  "detail": "Not authenticated"
}

دلایل: - هدر Authorization وجود ندارد - توکن ارسال نشده است

راه‌حل:

# اضافه کردن هدر
curl -X GET "{BASE_URL}/api/exchange/v1/symbols" \
  -H "Authorization: Bearer <your_jwt_token>"

2. Token has expired¶

کد: 401 Unauthorized

پاسخ:

{
  "detail": "Token has expired"
}

دلایل: - Access Token منقضی شده (معمولاً بعد از 24 ساعت)

راه‌حل:

# رفرش توکن
curl -X POST "{BASE_URL}/api/auth/v1/refresh" \
  -H "Content-Type: application/json" \
  -d '{"refresh_token": "'$REFRESH_TOKEN'"}'

3. Invalid authentication scheme¶

کد: 401 Unauthorized

پاسخ:

{
  "detail": "Invalid authentication scheme. Use 'Bearer <token>'"
}

دلایل: - فرمت هدر اشتباه است - کلمه Bearer وجود ندارد یا اشتباه نوشته شده

راه‌حل:

# ✅ صحیح
Authorization: Bearer eyJhbGc...

# ❌ اشتباه
Authorization: eyJhbGc...
Authorization: bearer eyJhbGc...  # حروف کوچک
Authorization: Bearer  eyJhbGc...  # دو فاصله

4. Invalid token format¶

کد: 401 Unauthorized

پاسخ:

{
  "detail": "Invalid token format"
}

دلایل:

توکن کامل کپی نشده
کاراکترهای اضافی یا فاصله
توکن دستکاری شده

راه‌حل:

# کپی کامل توکن
export JWT_TOKEN="eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJjbGllbnRfYWJjMTIzIiwidG9rZW5fdHlwZSI6ImFjY2VzcyIsImV4cCI6MTczNTY0MTYwMCwiaWF0IjoxNzM1NTU1MjAwLCJqdGkiOiJ0b2tlbl8xMjMiLCJzY29wZSI6ImFwaV9hY2Nlc3MifQ.signature"

5. Invalid token signature¶

کد: 401 Unauthorized

پاسخ:

{
  "detail": "Invalid token signature"
}

دلایل: - توکن دستکاری شده - توکن برای محیط دیگر است - کلید خصوصی تغییر کرده

راه‌حل:

# درخواست توکن جدید
curl -X POST "{BASE_URL}/api/auth/v1/login" \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": "your_client_id",
    "client_secret": "your_client_secret"
  }'

6. Invalid refresh token¶

کد: 401 Unauthorized

پاسخ:

{
  "detail": "Invalid refresh token"
}

دلایل:

Refresh Token اشتباه
Refresh Token منقضی شده
Refresh Token قبلاً استفاده شده

راه‌حل:

# درخواست توکن جدید با login
curl -X POST "{BASE_URL}/api/auth/v1/login" \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": "your_client_id",
    "client_secret": "your_client_secret"
  }'

7. Refresh token has expired¶

کد: 401 Unauthorized

پاسخ:

{
  "detail": "Refresh token has expired"
}

دلایل: - Refresh Token بیش از 30 روز اعتبار داشته

راه‌حل:

# درخواست توکن جدید با login
curl -X POST "{BASE_URL}/api/auth/v1/login" \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": "your_client_id",
    "client_secret": "your_client_secret"
  }'

8. Invalid client credentials¶

کد: 401 Unauthorized

پاسخ:

{
  "detail": "Invalid client credentials"
}

دلایل:

client_id اشتباه
client_secret اشتباه
کلاینت غیرفعال است

راه‌حل:

# بررسی صحت اطلاعات
echo "Client ID: $CLIENT_ID"
echo "Client Secret: $CLIENT_SECRET"

# درخواست اطلاعات جدید از بانک

خطاهای دسترسی (403)¶

1. Access denied¶

کد: 403 Forbidden

پاسخ:

{
  "detail": "Access denied"
}

دلایل:

کاربر به ریسورس دسترسی ندارد
نقش کاربر کافی نیست

راه‌حل:

بررسی دسترسی‌های کاربر
تماس با ادمین

2. Token belongs to different client¶

کد: 403 Forbidden

پاسخ:

{
  "detail": "Access denied. Token belongs to different client"
}

دلایل:

سعی در دسترسی به داده‌های کلاینت دیگر
توکن کلاینت دیگر استفاده می‌شود

راه‌حل:

# استفاده از توکن صحیح کلاینت خود
export JWT_TOKEN="your_client_token"

خطاهای یافت نشد (404)¶

1. Resource not found¶

کد: 404 Not Found

پاسخ:

{
  "detail": "User not found"
}

یا

{
  "detail": "Order not found"
}

دلایل:

شناسه اشتباه
ریسورس حذف شده
ریسورس وجود ندارد

راه‌حل:

# بررسی شناسه
echo "ID: $ITEM_ID"

# جستجوی آیتم
curl -X GET "{BASE_URL}/api/user/v1/users" \
  -H "Authorization: Bearer $JWT_TOKEN"

خطاهای اعتبارسنجی (422)¶

1. Field required¶

کد: 422 Unprocessable Entity

پاسخ:

{
  "detail": [
    {
      "loc": ["body", "username"],
      "msg": "field required",
      "type": "value_error.missing"
    }
  ]
}

دلایل:

فیلد اجباری ارسال نشده

راه‌حل:

# اضافه کردن فیلد مفقود
curl -X POST "{BASE_URL}/api/user/v1/users" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "john_doe",
    "email": "[email protected]"
  }'

2. Value too small¶

کد: 422 Unprocessable Entity

پاسخ:

{
  "detail": [
    {
      "loc": ["body", "quantity"],
      "msg": "value is less than minimum",
      "type": "value_error.number.not_ge",
      "ctx": {"limit_value": 0.0001}
    }
  ]
}

دلایل: - مقدار کمتر از حداقل مجاز

راه‌حل:

# استفاده از مقدار معتبر
curl -X POST "{BASE_URL}/api/exchange/v1/orders" \
  -H "Content-Type: application/json" \
  -d '{
    "symbol": "BTC-IRR",
    "side": "buy",
    "type": "limit",
    "quantity": "0.0001",  # حداقل مجاز
    "price": "1000000000"
  }'

3. Value too large¶

کد: 422 Unprocessable Entity

پاسخ:

{
  "detail": [
    {
      "loc": ["query", "limit"],
      "msg": "ensure this value is less than or equal to 100",
      "type": "value_error.number.not_le",
      "ctx": {"limit_value": 100}
    }
  ]
}

دلایل:

مقدار بیشتر از حداکثر مجاز

راه‌حل:

# استفاده از مقدار معتبر
GET /api/exchange/v1/orders?limit=100  # حداکثر

4. Invalid datetime format¶

کد: 422 Unprocessable Entity

پاسخ:

{
  "detail": [
    {
      "loc": ["query", "created_at_from"],
      "msg": "invalid datetime format, expected ISO 8601",
      "type": "value_error.datetime"
    }
  ]
}

دلایل:

فرمت تاریخ اشتباه
ISO 8601 رعایت نشده

راه‌حل:

# ✅ صحیح
created_at_from=2025-12-01T00:00:00Z

# ❌ اشتباه
created_at_from=2025/12/01
created_at_from=2025-12-01

5. Extra fields not permitted¶

کد: 422 Unprocessable Entity

پاسخ:

{
  "detail": [
    {
      "loc": ["query", "invalid_param"],
      "msg": "extra fields not permitted",
      "type": "value_error.extra"
    }
  ]
}

دلایل:

پارامتر نامعتبر ارسال شده

راه‌حل:

# بررسی پارامترهای مجاز
# فقط از پارامترهای مستند شده استفاده کنید

6. Invalid enum value¶

کد: 422 Unprocessable Entity

پاسخ:

{
  "detail": [
    {
      "loc": ["body", "side"],
      "msg": "value is not a valid enumeration member",
      "type": "type_error.enum",
      "ctx": {"enum_values": ["buy", "sell"]}
    }
  ]
}

دلایل: - مقدار از لیست مجاز انتخاب نشده

راه‌حل:

# ✅ صحیح
"side": "buy"  # یا "sell"

# ❌ اشتباه
"side": "BUY"
"side": "buy_or_sell"

خطاهای محدودیت نرخ (429)¶

1. Too many requests¶

کد: 429 Too Many Requests

پاسخ:

{
  "detail": "Too many requests"
}

یا

{
  "detail": "Rate limit exceeded. Try again in 60 seconds"
}

دلایل:

تعداد درخواست‌ها بیش از حد مجاز
ارسال درخواست‌ها با سرعت بالا

خطاهای سرور (5xx)¶

1. Internal Server Error¶

کد: 500 Internal Server Error

پاسخ:

{
  "detail": "Internal server error"
}

دلایل: - خطای داخلی سیستم

مشکل در پایگاه داده
باگ در کد

راه‌حل:

تماس با پشتیبانی

2. Service Unavailable¶

کد: 503 Service Unavailable

پاسخ:

{
  "detail": "Service temporarily unavailable"
}

دلایل:

سرور در حال نگهداری
مشکل در زیرساخت

3. Gateway Timeout¶

کد: 504 Gateway Timeout

پاسخ:

{
  "detail": "Gateway timeout"
}

چک‌لیست خطایابی¶

وقتی با خطا مواجه شدید:

بررسی کد وضعیت HTTP
4xx: مشکل از سمت کلاینت
5xx: مشکل از سمت سرور
بررسی پیام خطا
دقیقاً چه اتفاقی افتاده؟
چه فیلدی مشکل دارد؟
بررسی درخواست
URL صحیح است؟
هدرها کامل هستند؟
بدنه درخواست معتبر است؟
بررسی توکن
منقضی نشده؟
فرمت صحیح دارد؟
برای کلاینت صحیح است؟
تلاش مجدد
برای خطاهای 5xx
با زمان‌بندی مناسب

خلاصه¶

کد	معنی	دلیل رایج	راه‌حل
401	Unauthorized	توکن ندارد/منقضی شده	رفرش یا login مجدد
403	Forbidden	دسترسی ندارد	بررسی دسترسی‌ها
404	Not Found	منبع یافت نشد	بررسی شناسه
422	Unprocessable	داده نامعتبر	بررسی فیلدها
429	Too Many	محدودیت نرخ	افزایش زمان انتظار
500	Server Error	خطای داخلی	تلاش مجدد
503	Unavailable	سرویس قطع	تلاش مجدد

بعدی: مطالعه منطق دامنه بازار