مرجع خطاها

مرجع کامل کدهای خطای API اوربی‌وی‌پی‌ان، کدهای وضعیت HTTP و بهترین شیوه‌های رسیدگی به خطا در پروتکل‌های REST، gRPC و WebSocket.

مرجع API

مرجع خطاها

هر پاسخ API اوربی‌وی‌پی‌ان از ساختاری پیش‌بینی‌پذیر پیروی می‌کند. بیاموزید چگونه کدهای خطا را تفسیر کنید، با ناکامی‌ها به‌درستی کنار بیایید و یکپارچگی‌های تاب‌آور بسازید.


قالب استاندارد پاسخ

همهٔ نقاط پایانی API اوربی‌وی‌پی‌ان پوششی یکسان از JSON برمی‌گردانند. فیلد success بی‌درنگ می‌گوید درخواست موفق بوده یا نه، پس می‌توانید بدون وارسی کدهای وضعیت HTTP منطق خود را شاخه‌بندی کنید.

پاسخ موفق

درخواست با موفقیت کامل شد. بدنهٔ پاسخ فیلد data را با منبع درخواست‌شده یا تأییدیه دربر دارد.

پاسخ خطا

درخواست ناکام ماند. بدنهٔ پاسخ شیء error را با کدی ماشین‌خوان، پیامی انسان‌خوان و جزئیات اختیاری دربر دارد.

پاسخ موفق

200درخواست موفق
{
  "success": true,
  "data": {
    "id": "usr_abc123",
    "email": "user@example.com",
    "subscription": {
      "plan": "premium",
      "status": "active",
      "expiresAt": "2027-01-15T00:00:00Z"
    }
  }
}

پاسخ خطا

400درخواست ناکام
{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "The request body contains invalid fields.",
    "details": {
      "field": "email",
      "constraint": "required",
      "received": null
    }
  }
}

پوشش یکسان

هر پاسخ — موفق یا خطا — در همان ساختار سطح بالای یکسان پیچیده می‌شود. همیشه نخست بولی success را بررسی کنید، سپس بر همان اساس یا data یا error را بخوانید.


کدهای وضعیت HTTP

این API از کدهای استاندارد وضعیت HTTP برای نشان دادن ردهٔ کلی پاسخ استفاده می‌کند. جدول زیر همهٔ کدهای وضعیتی را که ممکن است ببینید پوشش می‌دهد.

وضعیتنامتوضیح
200OKدرخواست موفق بود. بدنهٔ پاسخ دادهٔ درخواست‌شده را دربر دارد.
201Createdمنبع تازه‌ای با موفقیت ساخته شد. بدنهٔ پاسخ منبع تازه را دربر دارد.
204No Contentدرخواست موفق بود اما بدنهٔ پاسخی ندارد (مثلاً پس از DELETE).
400Bad Requestدرخواست بدشکل است یا پارامترهای نامعتبر دارد. فیلد details را بررسی کنید.
401Unauthorizedاحراز هویت انجام نشده یا رمزینهٔ داده‌شده نامعتبر یا منقضی است.
403Forbiddenکاربر احراز هویت‌شده مجوز انجام این کار را ندارد.
404Not Foundمنبع درخواست‌شده وجود ندارد یا حذف شده است.
409Conflictدرخواست با وضعیت کنونی منبع تداخل دارد (مثلاً ایمیل تکراری).
422Unprocessable Entityدرخواست خوش‌شکل است اما از نظر معنایی نامعتبر است (مثلاً گذرواژهٔ سست).
429Too Many Requestsاز سقف نرخ گذشته‌اید. راهنمای محدودسازی نرخ را ببینید.
500Internal Server Errorخطای غیرمنتظره‌ای روی سرور رخ داد. با عقب‌نشینی نمایی دوباره تلاش کنید.
502Bad Gatewayسرویسی بالادست پاسخی نامعتبر برگرداند. معمولاً گذراست.
503Service Unavailableسرویس موقتاً برای نگهداری از دسترس خارج یا بیش‌ازحد بارگذاری شده است. بعداً تلاش کنید.

تنها به کدهای وضعیت HTTP تکیه نکنید

برای شناسایی دقیق خطا همیشه فیلد error.code را در بدنهٔ پاسخ وارسی کنید. چند شرط خطای متمایز می‌توانند یک کد وضعیت HTTP مشترک داشته باشند (مثلاً هم TOKEN_EXPIRED و هم TOKEN_INVALID کد 401 برمی‌گردانند).


کدهای خطای برنامه

هر پاسخ خطا رشتهٔ ماشین‌خوان error.code را دربر دارد. از این کدها برای ساخت منطق دقیق رسیدگی به خطا در برنامهٔ خود استفاده کنید.

خطاهای احراز هویت

کدوضعیت HTTPتوضیح
AUTH_REQUIRED401هیچ رمزینهٔ احراز هویتی داده نشده است. رمزینهٔ حامل معتبری در سرآیند Authorization بگنجانید.
TOKEN_EXPIRED401رمزینهٔ دسترسی منقضی شده است. با رمزینهٔ تازه‌سازی خود رمزینهٔ دسترسی تازه بگیرید.
TOKEN_INVALID401رمزینه بدشکل، باطل‌شده یا با کلیدی ناشناخته امضا شده است. دوباره احراز هویت کنید.
INSUFFICIENT_PERMISSIONS403کاربر احراز هویت‌شده نقش یا مجوز لازم برای این نقطهٔ پایانی را ندارد.
401خطای رمزینهٔ منقضی
{
  "success": false,
  "error": {
    "code": "TOKEN_EXPIRED",
    "message": "Your access token has expired. Please refresh your token or re-authenticate.",
    "details": {
      "expiredAt": "2026-02-08T11:30:00Z",
      "tokenType": "access"
    }
  }
}

خطاهای اعتبارسنجی

کدوضعیت HTTPتوضیح
VALIDATION_ERROR400یک یا چند فیلد درخواست از اعتبارسنجی رد نشد. شیء details مشخص می‌کند کدام فیلدها نامعتبرند.
INVALID_EMAIL422نشانی ایمیل داده‌شده قالب معتبری ندارد.
WEAK_PASSWORD422گذرواژه کمینه الزامات استحکام را برآورده نمی‌کند (دست‌کم ۸ نویسه، یک حرف بزرگ، یک رقم).
422خطای گذرواژهٔ سست
{
  "success": false,
  "error": {
    "code": "WEAK_PASSWORD",
    "message": "Password does not meet strength requirements.",
    "details": {
      "requirements": [
        "Minimum 8 characters",
        "At least one uppercase letter",
        "At least one number",
        "At least one special character"
      ],
      "failedChecks": ["uppercase", "special_character"]
    }
  }
}

خطاهای یافت نشدن منبع

کدوضعیت HTTPتوضیح
USER_NOT_FOUND404کاربری با شناسه یا ایمیل مشخص‌شده وجود ندارد.
SERVER_NOT_FOUND404سرور VPN درخواست‌شده وجود ندارد یا از رده خارج شده است.
DEVICE_NOT_FOUND404دستگاهی با شناسهٔ دستگاه مشخص‌شده وجود ندارد.
SUBSCRIPTION_NOT_FOUND404هیچ اشتراک فعالی برای این کاربر یافت نشد.

خطاهای تداخل

کدوضعیت HTTPتوضیح
EMAIL_ALREADY_EXISTS409حسابی با این نشانی ایمیل از پیش وجود دارد. به‌جای آن از نقطهٔ پایانی ورود استفاده کنید.
DEVICE_LIMIT_REACHED409کاربر به بیشینه شمار دستگاه‌های ثبت‌شده برای طرح اشتراک خود رسیده است.
409رسیدن به سقف دستگاه
{
  "success": false,
  "error": {
    "code": "DEVICE_LIMIT_REACHED",
    "message": "You have reached the maximum number of devices for your plan.",
    "details": {
      "currentDevices": 5,
      "maxDevices": 5,
      "plan": "standard",
      "upgradeUrl": "https://orbvpn.com/pricing"
    }
  }
}

خطاهای محدودسازی نرخ و سهمیه

کدوضعیت HTTPتوضیح
RATE_LIMITED429درخواست‌های بیش‌ازحد در یک پنجرهٔ زمانی. سرآیند X-RateLimit-Reset را رعایت کنید.
QUOTA_EXCEEDED429سهمیهٔ ماهانه یا روزانهٔ API طرح شما به پایان رسیده است. ارتقا دهید یا منتظر بازنشانی بمانید.

خطاهای سرور

کدوضعیت HTTPتوضیح
INTERNAL_ERROR500خطای غیرمنتظرهٔ سرور رخ داد. تیم OrbVPN خودکار باخبر می‌شود.
SERVICE_UNAVAILABLE503سرویس به دلیل نگهداری یا بار زیاد موقتاً در دسترس نیست.
UPSTREAM_ERROR502وابستگی‌ای بالادست پاسخی غیرمنتظره برگرداند. معمولاً گذراست.

خطاهای ویژهٔ VPN

کدوضعیت HTTPتوضیح
VPN_CONNECTION_FAILED500سرور VPN نتوانست تونلی برقرار کند. ممکن است سرور پر باشد یا مشکل داشته باشد.
DNS_RESOLUTION_FAILED500حل Smart DNS برای دامنهٔ درخواست‌شده ناکام ماند. مطمئن شوید دامنه در فهرست پشتیبانی‌شده هست.

خطاهای صورتحساب و پرداخت

کدوضعیت HTTPتوضیح
PAYMENT_FAILED400پرداخت پردازش نشد. روش پرداخت را بررسی کنید و دوباره تلاش کنید.
SUBSCRIPTION_EXPIRED403اشتراک کاربر منقضی شده است. این نقطهٔ پایانی به اشتراک معتبر نیاز دارد.
INSUFFICIENT_BALANCE400موجودی کیف‌پول کاربر برای این تراکنش کافی نیست.
403اشتراک منقضی‌شده
{
  "success": false,
  "error": {
    "code": "SUBSCRIPTION_EXPIRED",
    "message": "Your subscription has expired. Please renew to continue using this feature.",
    "details": {
      "expiredAt": "2026-01-31T23:59:59Z",
      "plan": "premium",
      "renewUrl": "https://orbvpn.com/dashboard/subscription"
    }
  }
}

بهترین شیوه‌های رسیدگی به خطا

این شیوه‌ها را دنبال کنید تا یکپارچگی‌هایی تاب‌آور بسازید که به‌درستی با خطاها کنار می‌آیند.

1

همیشه فیلد success را بررسی کنید

پیش از دسترسی به داده، مطمئن شوید success برابر true است. سریع‌ترین و قابل‌اتکاترین راه برای فهمیدن موفقیت درخواست همین است.

2

از کدهای خطا استفاده کنید، نه پیام‌ها

منطق شرطی خود را حول فیلد error.code بسازید (مثلاً TOKEN_EXPIRED)، نه رشتهٔ پیام انسان‌خوان. پیام‌ها ممکن است میان نسخه‌های API عوض شوند؛ کدها پایدارند.

3

منطق تلاش دوباره با عقب‌نشینی نمایی پیاده کنید

برای خطاهای گذرا (500، 502، 503، 429) درخواست را با عقب‌نشینی نمایی دوباره بفرستید. با تأخیر ۱ ثانیه شروع کنید و در هر تلاش دو برابرش کنید، تا بیشینه ۳۲ ثانیه.

4

انقضای رمزینه را خودکار مدیریت کنید

وقتی TOKEN_EXPIRED گرفتید، با رمزینهٔ تازه‌سازی خود رمزینهٔ دسترسی تازه بگیرید و سپس درخواست اصلی را دوباره بفرستید. مگر آنکه تازه‌سازی هم ناکام بماند، از کاربر نخواهید دوباره وارد شود.

5

جزئیات خطا را برای اشکال‌زدایی ثبت کنید

همیشه کل شیء خطا، از جمله فیلد details را ثبت کنید. این اطلاعات برای اشکال‌زدایی ناکامی‌های اعتبارسنجی و فهمیدن اینکه دقیقاً چه شد بی‌بدیل است.

راهبرد تلاش دوباره: عقب‌نشینی نمایی

برای خطاهای گذرا، عقب‌نشینی نمایی همراه با نوسان تصادفی پیاده کنید تا از مشکل هجوم هم‌زمان پرهیز شود.

Attempt 1: wait 1s + random(0-500ms)
Attempt 2: wait 2s + random(0-500ms)
Attempt 3: wait 4s + random(0-500ms)
Attempt 4: wait 8s + random(0-500ms)
Attempt 5: wait 16s + random(0-500ms)
Max retries: 5 | Max delay: 32s

خطاهای قابل تلاش دوباره

کدهای 500 (خطای داخلی)، 502 (دروازهٔ نامعتبر)، 503 (سرویس در دسترس نیست) و 429 (محدودشده) با عقب‌نشینی بی‌خطر قابل تکرارند.

خطاهای غیرقابل تلاش دوباره

کدهای 400 (درخواست نامعتبر)، 401 (بدون مجوز)، 403 (ممنوع)، 404 (یافت نشد)، 409 (تداخل) و 422 (پردازش‌ناپذیر) با تلاش دوباره حل نمی‌شوند.

جریان تازه‌سازی رمزینه

با دریافت 401 و TOKEN_EXPIRED نخست رمزینه را تازه کنید، سپس درخواست اصلی را دقیقاً یک بار دوباره بفرستید. اگر تازه‌سازی ناکام ماند، دوباره احراز هویت کنید.


نمونه‌های کد رسیدگی به خطا

نمونه‌های کاملی که رسیدگی نیرومند به خطا را در چهار زبان نشان می‌دهند.

# Make a request and handle the response
response=$(curl -s -w "\n%{http_code}" \
  -X GET https://api.orbai.world/api/v1/users/me \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json")

# Extract HTTP status code and body
http_code=$(echo "$response" | tail -n1)
body=$(echo "$response" | sed '$d')

case $http_code in
  200)
    echo "Success: $(echo $body | jq '.data')"
    ;;
  401)
    error_code=$(echo $body | jq -r '.error.code')
    if [ "$error_code" = "TOKEN_EXPIRED" ]; then
      echo "Token expired. Refreshing..."
      # Call refresh endpoint
      refresh_response=$(curl -s -X POST \
        https://api.orbai.world/api/v1/auth/refresh \
        -H "Content-Type: application/json" \
        -d "{\"refreshToken\": \"$REFRESH_TOKEN\"}")
      ACCESS_TOKEN=$(echo $refresh_response | jq -r '.data.token')
      # Retry original request with new token
    else
      echo "Auth error: $error_code"
    fi
    ;;
  429)
    reset=$(echo "$response" | grep -i "X-RateLimit-Reset" | cut -d' ' -f2)
    echo "Rate limited. Retry after: $reset"
    ;;
  *)
    echo "Error $http_code: $(echo $body | jq -r '.error.message')"
    ;;
esac

سناریوهای رایج خطا

نبود سرآیند Authorization

هر نقطهٔ پایانی محافظت‌شده به Authorization: Bearer <token> نیاز دارد. اگر نباشد، AUTH_REQUIRED (401) می‌گیرید.

رمزینهٔ دسترسی منقضی‌شده

رمزینه‌های دسترسی پس از ۲۴ ساعت منقضی می‌شوند. برای گرفتن رمزینهٔ تازه POST /api/v1/auth/refresh را با رمزینهٔ تازه‌سازی خود فراخوانی کنید.

ناکامی‌های اعتبارسنجی

شیء details را با دقت بخوانید. دقیقاً فیلد، محدودیت و مقدار دریافت‌شده‌ای را که خطا را ساخته مشخص می‌کند.

محدودسازی نرخ

اگر RATE_LIMITED (429) گرفتید، سرآیند X-RateLimit-Reset را بررسی کنید و پیش از تلاش دوباره صبر کنید. راهنمای محدودسازی نرخ را ببینید.

نکات اشکال‌زدایی

با هر درخواست سرآیند یکتای X-Request-ID را بگنجانید. اگر لازم شد دربارهٔ خطایی با پشتیبانی تماس بگیرید، این شناسه را بدهید تا تیم بتواند درخواست را در گزارش‌های ما دنبال کند.


کمک لازم دارید؟

اگر با خطایی روبه‌رو شدید که اینجا فهرست نشده یا برای اشکال‌زدایی مشکل یکپارچگی کمک می‌خواهید، با تیم پشتیبانی توسعه‌دهندگان ما تماس بگیرید.

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