{
  "title": "کدهای وضعیت HTTP",
  "slug": "team/backend/standard/http-status-codes",
  "url": "/docs/team/backend/standard/http-status-codes",
  "frontmatter": {
    "layout": "doc",
    "title": "کدهای وضعیت HTTP",
    "description": "کدهای مجاز و ممنوعه — راهنمای استفاده از HTTP Status Codes در API",
    "version": "1.0.0",
    "status": "PRIVATE",
    "author": "xoxxel",
    "owner": "xoxxel",
    "created_at": "2026-06-07",
    "updated_at": "2026-06-07",
    "tags": "",
    "reviewers": ""
  },
  "sections": [
    {
      "level": 1,
      "heading": "کدهای وضعیت HTTP",
      "content": "**HTTP Status Codes**\n\nنسخه 2.0 | الزامی برای همه سرویس‌ها\n\n> **مرجع اصلی:** [راهنمای طراحی API](../../platform/api/api-design-guidelines#۱۲-کدهای-وضعیت-http-status-codes) — این سند جزئیات فنی بیشتری ارائه می‌دهد.\n>\n> منبع اصلی کدهای خطا (Error Codes) در [nons-api/contracts/errors.proto](/docs/team/platform/package/contract_catalog) (Platform) و هر سرویس (Domain) — این سند فقط HTTP Status Codes را مشخص می‌کند\n\n---"
    },
    {
      "level": 2,
      "heading": "1. جدول کدهای مجاز",
      "content": "| کد | نام | زمان استفاده |\n|---|---|---|\n| `200` | OK | موفقیت با بدنه — دریافت منبع، لیست |\n| `201` | Created | منبع جدید ایجاد شد — POST |\n| `204` | No Content | موفقیت بدون بدنه — DELETE، بروزرسانی وضعیت |\n| `400` | Bad Request | ورودی نامعتبر — validation error |\n| `401` | Unauthorized | احراز هویت نشده — توکن缺失 یا نامعتبر |\n| `403` | Forbidden | احراز هویت شده اما مجاز نیست |\n| `404` | Not Found | منبع یافت نشد |\n| `409` | Conflict | تداخل — نام تکراری، انتقال وضعیت نامعتبر |\n| `422` | Unprocessable Entity | ورودی معتبر اما منطقاً نادرست |\n| `424` | Failed Dependency | وابستگی سرویس در دسترس نیست — خطای تبدیل ارز |\n| `429` | Too Many Requests | محدودیت نرخ فراتر رفته |\n| `500` | Internal Server Error | خطای غیرمنتظره سرور |\n\n---"
    },
    {
      "level": 2,
      "heading": "2. قوانین طلایی",
      "content": "| قانون | توضیح |\n|---|---|\n| **هرگز برای خطا `200` برنگردانید** | خطا همیشه با کد خطا (4xx/5xx) برگردانده شود |\n| **هرگز برای اشتباه کلاینت `500` برنگردانید** | خطای کلاینت = 4xx |\n| **هرگز `5xx` را swallow نکنید** | خطای سرور باید ثبت و گزارش شود |\n| **کد دقیق** | از نزدیک‌ترین کد به ماهیت خطا استفاده کنید |\n\n---"
    },
    {
      "level": 2,
      "heading": "3. توضیح هر کد",
      "content": ""
    },
    {
      "level": 3,
      "heading": "2xx — موفقیت",
      "content": "| کد | سناریوی دقیق | مثال |\n|---|---|---|\n| `200` | GET منبع, GET لیست, PATCH موفق | دریافت جزئیات سفارش |\n| `201` | POST موفق — ایجاد منبع | ایجاد سفارش جدید |\n| `204` | DELETE موفق, بروزرسانی وضعیت (بدون بازگشت بدنه) | حذف سفارش |"
    },
    {
      "level": 3,
      "heading": "4xx — خطای کلاینت",
      "content": "| کد | سناریوی دقیق | مثال |\n|---|---|---|\n| `400` | JSON نامعتبر, validation, فیلد缺失 | `email` فرمت اشتباه دارد |\n| `401` | بدون توکن, توکن منقضی, توکن نامعتبر | درخواست بدون `Authorization` header |\n| `403` | نقش کاربر مجاز نیست | کاربر عادی می‌خواهد ادمین کند |\n| `404` | منبع با این ID وجود ندارد | `GET /orders/0000` |\n| `409` | نام تکراری, وضعیت غیرمجاز, شرط failed | تلاش برای پرداخت سفارش قبلاً پرداخت شده |\n| `422` | ورودی structurally معتبر اما منطقاً غلط | موجودی کافی نیست |\n| `424` | سرویس وابسته (مثلاً currency-service) در دسترس نیست | تبدیل ارز ناموفق |\n| `429` | محدودیت rate limit | بیش از ۱۰۰ درخواست در دقیقه |"
    },
    {
      "level": 3,
      "heading": "5xx — خطای سرور",
      "content": "| کد | سناریوی دقیق | مثال |\n|---|---|---|\n| `500` | خطای غیرمنتظره, دیتابیس Down, Null Pointer | اتصال به دیتابیس قطع شده |\n\n---"
    },
    {
      "level": 2,
      "heading": "4. مثال خطاها با کد مناسب",
      "content": "```json\n// 400 — Bad Request\n{\n  \"success\": false,\n  \"error\": {\n    \"code\": \"VALIDATION_ERROR\",\n    \"message\": \"Request validation failed\",\n    \"details\": [{ \"field\": \"email\", \"message\": \"Invalid email format\" }]\n  }\n}\n\n// 401 — Unauthorized\n{\n  \"success\": false,\n  \"error\": {\n    \"code\": \"AUTH_TOKEN_EXPIRED\",\n    \"message\": \"Access token has expired\",\n    \"details\": []\n  }\n}\n\n// 403 — Forbidden\n{\n  \"success\": false,\n  \"error\": {\n    \"code\": \"FORBIDDEN\",\n    \"message\": \"You do not have permission to perform this action\",\n    \"details\": []\n  }\n}\n\n// 404 — Not Found\n{\n  \"success\": false,\n  \"error\": {\n    \"code\": \"ORDER_NOT_FOUND\",\n    \"message\": \"The requested order does not exist\",\n    \"details\": []\n  }\n}\n\n// 409 — Conflict\n{\n  \"success\": false,\n  \"error\": {\n    \"code\": \"ORDER_INVALID_STATUS\",\n    \"message\": \"Cannot pay an already paid order\",\n    \"details\": []\n  }\n}\n\n// 422 — Unprocessable Entity\n{\n  \"success\": false,\n  \"error\": {\n    \"code\": \"INSUFFICIENT_BALANCE\",\n    \"message\": \"Buyer does not have sufficient balance\",\n    \"details\": []\n  }\n}\n\n// 429 — Too Many Requests\n{\n  \"success\": false,\n  \"error\": {\n    \"code\": \"RATE_LIMIT_EXCEEDED\",\n    \"message\": \"Too many requests. Please try again later\",\n    \"details\": []\n  }\n}\n```\n\n---"
    },
    {
      "level": 2,
      "heading": "5. کدهای ممنوعه",
      "content": "| کد | دلیل ممنوعیت |\n|---|---|\n| `402` | Payment Required — رزرو شده، برای پروژه ما معنی ندارد |\n| `406` | Not Acceptable — از content negotiation استفاده نمی‌کنیم |\n| `413` | Payload Too Large — با validation در 400 مدیریت می‌شود |\n| `415` | Unsupported Media Type — همه سرویس‌ها JSON می‌گیرند |\n| `423` | Locked — با 409 مدیریت می‌شود |\n| `502` | Bad Gateway — پروکسی معکوس مدیریت می‌کند |\n| `503` | Service Unavailable — با 500 مدیریت می‌شود |\n| `504` | Gateway Timeout — پروکسی معکوس مدیریت می‌کند |\n\n---"
    },
    {
      "level": 2,
      "heading": "خلاصه",
      "content": "| دسته | کدها |\n|---|---|\n| موفقیت | `200`, `201`, `204` |\n| خطای کلاینت | `400`, `401`, `403`, `404`, `409`, `422`, `424`, `429` |\n| خطای سرور | `500` |"
    }
  ]
}