مرجع خطاها
مرجع کامل کدهای خطای API اوربیویپیان، کدهای وضعیت HTTP و بهترین شیوههای رسیدگی به خطا در پروتکلهای REST، gRPC و WebSocket.
مرجع خطاها
هر پاسخ API اوربیویپیان از ساختاری پیشبینیپذیر پیروی میکند. بیاموزید چگونه کدهای خطا را تفسیر کنید، با ناکامیها بهدرستی کنار بیایید و یکپارچگیهای تابآور بسازید.
قالب استاندارد پاسخ
همهٔ نقاط پایانی API اوربیویپیان پوششی یکسان از JSON برمیگردانند. فیلد success بیدرنگ میگوید درخواست موفق بوده یا نه، پس میتوانید بدون وارسی کدهای وضعیت HTTP منطق خود را شاخهبندی کنید.
پاسخ موفق
درخواست با موفقیت کامل شد. بدنهٔ پاسخ فیلد data را با منبع درخواستشده یا تأییدیه دربر دارد.
پاسخ خطا
درخواست ناکام ماند. بدنهٔ پاسخ شیء error را با کدی ماشینخوان، پیامی انسانخوان و جزئیات اختیاری دربر دارد.
پاسخ موفق
{
"success": true,
"data": {
"id": "usr_abc123",
"email": "user@example.com",
"subscription": {
"plan": "premium",
"status": "active",
"expiresAt": "2027-01-15T00:00:00Z"
}
}
}پاسخ خطا
{
"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 برای نشان دادن ردهٔ کلی پاسخ استفاده میکند. جدول زیر همهٔ کدهای وضعیتی را که ممکن است ببینید پوشش میدهد.
| وضعیت | نام | توضیح |
|---|---|---|
| 200 | OK | درخواست موفق بود. بدنهٔ پاسخ دادهٔ درخواستشده را دربر دارد. |
| 201 | Created | منبع تازهای با موفقیت ساخته شد. بدنهٔ پاسخ منبع تازه را دربر دارد. |
| 204 | No Content | درخواست موفق بود اما بدنهٔ پاسخی ندارد (مثلاً پس از DELETE). |
| 400 | Bad Request | درخواست بدشکل است یا پارامترهای نامعتبر دارد. فیلد details را بررسی کنید. |
| 401 | Unauthorized | احراز هویت انجام نشده یا رمزینهٔ دادهشده نامعتبر یا منقضی است. |
| 403 | Forbidden | کاربر احراز هویتشده مجوز انجام این کار را ندارد. |
| 404 | Not Found | منبع درخواستشده وجود ندارد یا حذف شده است. |
| 409 | Conflict | درخواست با وضعیت کنونی منبع تداخل دارد (مثلاً ایمیل تکراری). |
| 422 | Unprocessable Entity | درخواست خوششکل است اما از نظر معنایی نامعتبر است (مثلاً گذرواژهٔ سست). |
| 429 | Too Many Requests | از سقف نرخ گذشتهاید. راهنمای محدودسازی نرخ را ببینید. |
| 500 | Internal Server Error | خطای غیرمنتظرهای روی سرور رخ داد. با عقبنشینی نمایی دوباره تلاش کنید. |
| 502 | Bad Gateway | سرویسی بالادست پاسخی نامعتبر برگرداند. معمولاً گذراست. |
| 503 | Service Unavailable | سرویس موقتاً برای نگهداری از دسترس خارج یا بیشازحد بارگذاری شده است. بعداً تلاش کنید. |
تنها به کدهای وضعیت HTTP تکیه نکنید
برای شناسایی دقیق خطا همیشه فیلد error.code را در بدنهٔ پاسخ وارسی کنید. چند شرط خطای متمایز میتوانند یک کد وضعیت HTTP مشترک داشته باشند (مثلاً هم TOKEN_EXPIRED و هم TOKEN_INVALID کد 401 برمیگردانند).
کدهای خطای برنامه
هر پاسخ خطا رشتهٔ ماشینخوان error.code را دربر دارد. از این کدها برای ساخت منطق دقیق رسیدگی به خطا در برنامهٔ خود استفاده کنید.
خطاهای احراز هویت
| کد | وضعیت HTTP | توضیح |
|---|---|---|
AUTH_REQUIRED | 401 | هیچ رمزینهٔ احراز هویتی داده نشده است. رمزینهٔ حامل معتبری در سرآیند Authorization بگنجانید. |
TOKEN_EXPIRED | 401 | رمزینهٔ دسترسی منقضی شده است. با رمزینهٔ تازهسازی خود رمزینهٔ دسترسی تازه بگیرید. |
TOKEN_INVALID | 401 | رمزینه بدشکل، باطلشده یا با کلیدی ناشناخته امضا شده است. دوباره احراز هویت کنید. |
INSUFFICIENT_PERMISSIONS | 403 | کاربر احراز هویتشده نقش یا مجوز لازم برای این نقطهٔ پایانی را ندارد. |
{
"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_ERROR | 400 | یک یا چند فیلد درخواست از اعتبارسنجی رد نشد. شیء details مشخص میکند کدام فیلدها نامعتبرند. |
INVALID_EMAIL | 422 | نشانی ایمیل دادهشده قالب معتبری ندارد. |
WEAK_PASSWORD | 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_FOUND | 404 | کاربری با شناسه یا ایمیل مشخصشده وجود ندارد. |
SERVER_NOT_FOUND | 404 | سرور VPN درخواستشده وجود ندارد یا از رده خارج شده است. |
DEVICE_NOT_FOUND | 404 | دستگاهی با شناسهٔ دستگاه مشخصشده وجود ندارد. |
SUBSCRIPTION_NOT_FOUND | 404 | هیچ اشتراک فعالی برای این کاربر یافت نشد. |
خطاهای تداخل
| کد | وضعیت HTTP | توضیح |
|---|---|---|
EMAIL_ALREADY_EXISTS | 409 | حسابی با این نشانی ایمیل از پیش وجود دارد. بهجای آن از نقطهٔ پایانی ورود استفاده کنید. |
DEVICE_LIMIT_REACHED | 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_LIMITED | 429 | درخواستهای بیشازحد در یک پنجرهٔ زمانی. سرآیند X-RateLimit-Reset را رعایت کنید. |
QUOTA_EXCEEDED | 429 | سهمیهٔ ماهانه یا روزانهٔ API طرح شما به پایان رسیده است. ارتقا دهید یا منتظر بازنشانی بمانید. |
خطاهای سرور
| کد | وضعیت HTTP | توضیح |
|---|---|---|
INTERNAL_ERROR | 500 | خطای غیرمنتظرهٔ سرور رخ داد. تیم OrbVPN خودکار باخبر میشود. |
SERVICE_UNAVAILABLE | 503 | سرویس به دلیل نگهداری یا بار زیاد موقتاً در دسترس نیست. |
UPSTREAM_ERROR | 502 | وابستگیای بالادست پاسخی غیرمنتظره برگرداند. معمولاً گذراست. |
خطاهای ویژهٔ VPN
| کد | وضعیت HTTP | توضیح |
|---|---|---|
VPN_CONNECTION_FAILED | 500 | سرور VPN نتوانست تونلی برقرار کند. ممکن است سرور پر باشد یا مشکل داشته باشد. |
DNS_RESOLUTION_FAILED | 500 | حل Smart DNS برای دامنهٔ درخواستشده ناکام ماند. مطمئن شوید دامنه در فهرست پشتیبانیشده هست. |
خطاهای صورتحساب و پرداخت
| کد | وضعیت HTTP | توضیح |
|---|---|---|
PAYMENT_FAILED | 400 | پرداخت پردازش نشد. روش پرداخت را بررسی کنید و دوباره تلاش کنید. |
SUBSCRIPTION_EXPIRED | 403 | اشتراک کاربر منقضی شده است. این نقطهٔ پایانی به اشتراک معتبر نیاز دارد. |
INSUFFICIENT_BALANCE | 400 | موجودی کیفپول کاربر برای این تراکنش کافی نیست. |
{
"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"
}
}
}بهترین شیوههای رسیدگی به خطا
این شیوهها را دنبال کنید تا یکپارچگیهایی تابآور بسازید که بهدرستی با خطاها کنار میآیند.
همیشه فیلد success را بررسی کنید
پیش از دسترسی به داده، مطمئن شوید success برابر true است. سریعترین و قابلاتکاترین راه برای فهمیدن موفقیت درخواست همین است.
از کدهای خطا استفاده کنید، نه پیامها
منطق شرطی خود را حول فیلد error.code بسازید (مثلاً TOKEN_EXPIRED)، نه رشتهٔ پیام انسانخوان. پیامها ممکن است میان نسخههای API عوض شوند؛ کدها پایدارند.
منطق تلاش دوباره با عقبنشینی نمایی پیاده کنید
برای خطاهای گذرا (500، 502، 503، 429) درخواست را با عقبنشینی نمایی دوباره بفرستید. با تأخیر ۱ ثانیه شروع کنید و در هر تلاش دو برابرش کنید، تا بیشینه ۳۲ ثانیه.
انقضای رمزینه را خودکار مدیریت کنید
وقتی TOKEN_EXPIRED گرفتید، با رمزینهٔ تازهسازی خود رمزینهٔ دسترسی تازه بگیرید و سپس درخواست اصلی را دوباره بفرستید. مگر آنکه تازهسازی هم ناکام بماند، از کاربر نخواهید دوباره وارد شود.
جزئیات خطا را برای اشکالزدایی ثبت کنید
همیشه کل شیء خطا، از جمله فیلد 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 را بگنجانید. اگر لازم شد دربارهٔ خطایی با پشتیبانی تماس بگیرید، این شناسه را بدهید تا تیم بتواند درخواست را در گزارشهای ما دنبال کند.
کمک لازم دارید؟
اگر با خطایی روبهرو شدید که اینجا فهرست نشده یا برای اشکالزدایی مشکل یکپارچگی کمک میخواهید، با تیم پشتیبانی توسعهدهندگان ما تماس بگیرید.