رفع خطاهای SDK در Postman

راهنمای سریع رفع خطاهای SDK Generator #

اگر هنگام استفاده از Postman SDK Generator یا دستورهای CLI با خطا روبه‌رو شدید، اول نوع عملیات را مشخص کنید: تولید SDK، گرفتن خروجی، اتصال به repository، ساخت PR یا دانلود artifact. سپس پیام خطا را با بخش‌های زیر تطبیق دهید.

در بیشتر خطاها، راه‌حل از یکی از این موارد شروع می‌شود: ورود دوباره به Postman CLI، بررسی شناسه collection یا build، اصلاح فایل postman-sdk.config.json، انتخاب زبان معتبر، یا بررسی دسترسی workspace و repository.

خطاهای احراز هویت و دسترسی #

CLI وارد نشده است #

اگر CLI نتواند حساب شما را تشخیص دهد، معمولا باید دوباره وارد شوید.

postman login

بعد از ورود، دستور قبلی را دوباره اجرا کنید. اگر در CI/CD کار می‌کنید، مطمئن شوید token یا متغیر محیطی مربوط به Postman درست تنظیم شده است.

خطاهای دستور generate #

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

اگر collection یا specification معتبر نباشد، SDK ساخته نمی‌شود. فایل ورودی را در Postman باز کنید و مطمئن شوید ساختار آن سالم است، نام API و نسخه مشخص شده، و requestهای اصلی بدون مشکل تعریف شده‌اند.

خطاهای شناسه Collection #

اگر شناسه collection اشتباه باشد، Postman نمی‌تواند منبع را پیدا کند. شناسه را از URL یا محیط Postman دوباره کپی کنید و مطمئن شوید به همان workspace دسترسی دارید.

خطاهای انتخاب زبان #

زبان‌ها باید با نام‌های قابل قبول SDK Generator نوشته شوند. نمونه‌های رایج:

typescript
java
kotlin
python
csharp
go
php
ruby
rust

اگر چند زبان انتخاب می‌کنید، مقدارها را در آرایه languages فایل پیکربندی قرار دهید و غلط املایی نداشته باشید.

خطاهای فایل پیکربندی #

اگر فایل postman-sdk.config.json مشکل داشته باشد، تولید SDK متوقف می‌شود. این موارد را بررسی کنید:

• فایل JSON معتبر باشد و comma اضافه یا جاافتاده نداشته باشد.
• sdkName، apiName، apiVersion و languages درست تنظیم شده باشند.
• گزینه‌های زبان در بخش درست مثل languageOptions قرار گرفته باشند.
• مقدارهای boolean مثل true و false به صورت string نوشته نشده باشند.

خطاهای API تولید SDK #

اگر سرویس تولید SDK خطا بدهد، چند دقیقه بعد دوباره تلاش کنید. اگر خطا تکرار شد، ورودی را کوچک‌تر و ساده‌تر کنید، collection/specification را اعتبارسنجی کنید و سپس دوباره دستور را اجرا کنید.

خطاهای ساخت Pull Request #

برای ساخت PR، اتصال repository باید فعال و معتبر باشد. دسترسی write به repository، branch مقصد، نام branch جدید و تنظیمات provider مثل GitHub را بررسی کنید.

خطاهای دستور list #

وضعیت نامعتبر #

اگر وضعیت build را فیلتر می‌کنید، مقدار status باید معتبر باشد. مقدارهای رایج معمولا وضعیت‌هایی مثل pending، running، completed یا failed هستند.

خطاهای API #

اگر دستور list نتواند فهرست buildها را بگیرد، اتصال اینترنت، ورود CLI و دسترسی workspace را بررسی کنید. در صورت خطای موقت سرویس، کمی بعد دوباره تلاش کنید.

خطاهای دانلود #

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

خطاهای دستور get یا fetch #

شناسه Build نامعتبر #

Build ID باید دقیقا همان شناسه‌ای باشد که از خروجی دستورهای قبلی یا داشبورد دریافت کرده‌اید. اگر شناسه را دستی وارد می‌کنید، فاصله یا کاراکتر اضافه نداشته باشد.

Build پیدا نشد #

اگر build پیدا نمی‌شود، ممکن است در workspace دیگری ساخته شده باشد، حذف شده باشد، یا حساب فعلی شما به آن دسترسی نداشته باشد. ابتدا با دستور list buildهای قابل مشاهده را بررسی کنید.

مشکل دانلود خروجی #

برای دانلود artifact، build باید کامل شده باشد. اگر build هنوز در حال اجراست یا شکست خورده، خروجی قابل دانلود نیست. وضعیت build را بررسی کنید و بعد از کامل شدن دوباره دانلود کنید.

خطاهای دستور connect #

Provider نامعتبر #

اگر provider اشتباه باشد، اتصال repository ساخته نمی‌شود. نام provider را مطابق گزینه‌های پشتیبانی‌شده وارد کنید و مطمئن شوید حساب شما اجازه اتصال دارد.

زبان نامعتبر #

اگر اتصال را برای زبان خاصی می‌سازید، همان نام زبان‌های معتبر SDK Generator را استفاده کنید. برای مثال typescript را به جای شکل‌های غیررسمی یا متفاوت بنویسید.

خطاهای Workspace #

Workspace باید وجود داشته باشد و حساب شما به آن دسترسی داشته باشد. اگر عضو workspace نیستید یا دسترسی شما محدود است، از مدیر workspace دسترسی لازم را بگیرید.

خطاهای OAuth #

برای اتصال repository، جریان OAuth باید کامل شود. اگر صفحه مجوز بسته شد یا مجوز کافی ندادید، اتصال را از ابتدا تکرار کنید و scopeهای لازم را تایید کنید.

خطاهای Repository #

repository باید وجود داشته باشد و حساب متصل‌شده باید به آن دسترسی داشته باشد. برای ساخت PR یا push، دسترسی write لازم است.

خطاهای Integration #

اگر integration درست کار نمی‌کند، اتصال provider را قطع و دوباره وصل کنید. همچنین بررسی کنید organization یا repository مورد نظر محدودیت امنیتی اضافه نداشته باشد.

خطاهای پایان Build #

وضعیت Build #

اگر build با موفقیت تمام نشده باشد، خروجی SDK آماده نیست. وضعیت build را بررسی کنید. اگر failed است، خطای اصلی را از گزارش build بخوانید و سپس فایل ورودی یا تنظیمات را اصلاح کنید.

دانلود Artifact #

اگر build کامل شده اما artifact دانلود نمی‌شود، ممکن است artifact منقضی شده، حذف شده یا موقتا در دسترس نباشد. در صورت نیاز، build را دوباره اجرا کنید.

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

اگر collection، specification یا فایل ورودی با خطای validation روبه‌رو شد، آن را در Postman یا ابزار اعتبارسنجی OpenAPI بررسی کنید. برای تولید SDK، نام، نسخه، مسیرها، requestها و schemaهای اصلی باید قابل پردازش باشند.

خطاهای پیکربندی #

برای خطاهای configuration، این چک‌لیست کوتاه را دنبال کنید:

• نام فایل postman-sdk.config.json درست باشد.
• فایل در مسیری باشد که CLI انتظار دارد، یا مسیر آن را صریح مشخص کرده باشید.
• ساختار JSON معتبر باشد.
• مقدارهای اصلی مثل sdkName، baseUrl، languages و auth با مستندات هماهنگ باشند.

خطاهای زبان #

اگر پیام خطا به language format اشاره می‌کند، معمولا نام زبان اشتباه نوشته شده یا ساختار آرایه زبان‌ها درست نیست. نمونه درست:

{
  "languages": ["typescript", "python", "java"]
}

خطاهای فایل سیستم #

خطاهای دانلود #

اگر CLI نتواند فایل را ذخیره کند، مسیر خروجی را عوض کنید یا مجوز نوشتن پوشه را اصلاح کنید. در سیستم‌های CI، مسیر workspace و cache را هم بررسی کنید.

خطاهای Artifact #

اگر artifact ناقص یا خراب است، build را دوباره اجرا کنید. همچنین مطمئن شوید فایل zip یا خروجی SDK کامل دانلود شده و هنگام extract خطا نداده است.

خطاهای HTTP #

کد ۴۲۹: محدودیت نرخ درخواست #

تعداد درخواست‌ها زیاد بوده است. کمی صبر کنید و دوباره تلاش کنید. در automation، بین درخواست‌ها delay بگذارید.

کد ۴۰۳: دسترسی ممنوع #

حساب فعلی مجوز لازم را ندارد. ورود CLI، نقش کاربر، دسترسی workspace و دسترسی repository را بررسی کنید.

کد ۴۰۴: پیدا نشد #

شناسه منبع، build، collection، workspace یا repository اشتباه است یا به آن دسترسی ندارید. مقدارها را دوباره از منبع اصلی کپی کنید.

کدهای ۵۰۰ و بالاتر #

این خطاها معمولا سمت سرویس هستند. چند دقیقه بعد دوباره امتحان کنید. اگر تکرار شد، ورودی، زمان رخداد، build ID و پیام خطا را برای بررسی نگه دارید.

قالب کلی پیام خطا #

برای عیب‌یابی بهتر، هنگام گزارش مشکل این اطلاعات را نگه دارید:

• دستوری که اجرا کرده‌اید.
• پیام خطای کامل.
• نسخه Postman CLI.
• نام زبان یا زبان‌های انتخاب‌شده.
• شناسه collection، build یا workspace، اگر در خطا نقش دارد.
• بخشی از فایل postman-sdk.config.json که به خطا مربوط است.

با این اطلاعات معمولا می‌توان سریع‌تر تشخیص داد مشکل از ورود، دسترسی، فایل پیکربندی، منبع ورودی یا سرویس تولید SDK است.

منبع آموزشی: Postman Docs، بازنویسی و ساده‌سازی‌شده برای کاربران فارسی‌زبان.