خطاها

خطاهای دسترسی روشا (401، 403 و 429) همیشه JSON با دو فیلد detail و code هستند. در کد خود بر اساس code تصمیم بگیرید، نه متن detail. خطاهای 404 و 422 فیلد code ندارند و دلیل را در detail می‌گویند.

{"detail": "Your plan does not include intraday data.", "code": "plan_forbids"}

هر خطا چه معنایی دارد و چه باید کرد؟

این جدول همهٔ پاسخ‌های خطای /v1 و /mcp را دارد.

وضعیت	code	معنا	چه کنید	تلاش مجدد؟
401	key_required	کلیدی فرستاده نشده است.	نام سرآیند را بررسی کنید: Authorization: Bearer <key> (با فاصله بعد از Bearer) یا X-API-Key: <key>. کلید در query string خوانده نمی‌شود.	نه؛ اول درخواست را اصلاح کنید
401	invalid_key	کلید شناخته نشد: غلط تایپی، ناقص کپی شده، یا کلید محیط دیگری است.	کلید را کامل و بدون فاصلهٔ اضافه کپی کنید. پیشوند آن را با پنل مقایسه کنید.	نه
401	key_revoked	کلید در پنل باطل یا چرخانده شده است.	در پنل کلید تازه بسازید و جایگزین کنید.	نه
401	key_expired	تاریخ انقضای کلید گذشته است.	در پنل کلید تازه بسازید.	نه
403	account_suspended	حساب فعال نیست.	با پشتیبانی تماس بگیرید.	نه
403	no_subscription	امروز اشتراک جاری ندارید، یا پلن شما غیرفعال شده است.	تاریخ شروع و پایان اشتراک را در پنل ببینید. اشتراکی که فردا شروع می‌شود امروز جاری نیست.	نه
403	plan_forbids	پلن شما این خانوادهٔ داده (history، intraday یا mcp) را ندارد. نام خانواده در detail آمده است.	پلن را در قیمت‌ها ارتقا دهید یا از endpoint دیگری استفاده کنید.	نه
429	rate_limited	به سقف درخواست در دقیقهٔ پلن رسیده‌اید.	به اندازهٔ Retry-After ثانیه صبر کنید (تا شروع دقیقهٔ بعد).	بله، پس از Retry-After
429	quota_exceeded	سهمیهٔ روزانهٔ کلید تمام شده است. Retry-After برابر 3600 است.	سهمیه نیمه‌شب به وقت تهران صفر می‌شود. کار را متوقف کنید یا پلن را ارتقا دهید.	نه تا نیمه‌شب تهران
404	ندارد	نماد، صندوق یا مسیر پیدا نشد.	ref را با جست‌وجو پیدا کنید؛ نشانی مسیر را بررسی کنید.	نه
422	ندارد	پارامتر نادرست: قالب تاریخ، پارامتر الزامیِ جاافتاده، یا limit بیشتر از سقف.	detail را بخوانید و پارامتر را اصلاح کنید.	نه

پاسخ‌های 401 سرآیند WWW-Authenticate: Bearer دارند. پاسخ‌های 429 سرآیند Retry-After دارند.

متن detail در خطاهای دسترسی چیست؟

متن detail انگلیسی و برای خواندن انسان است؛ ممکن است تغییر کند. مقدار code ثابت می‌ماند.

code	detail
key_required	API key required: Authorization: Bearer <key>.
invalid_key	API key is not valid.
key_revoked	API key has been revoked.
key_expired	API key has expired.
account_suspended	Account is suspended. Contact support.
no_subscription	No active subscription for this account.
plan_forbids	Your plan does not include intraday data. (یا history یا mcp)
rate_limited	Rate limit of 30 requests/minute exceeded. (عدد، سقف پلن شماست)
quota_exceeded	Daily quota of 1000 requests exceeded. (عدد، سهمیهٔ پلن شماست)

پاسخ 404 چه شکلی دارد؟

404 یعنی ref به هیچ نماد یا صندوقی نخورد، یا مسیر وجود ندارد. بدنه فقط detail دارد.

{"detail": "instrument not found: xyz123"}

{"detail": "fund 'nope' not found"}

مسیر ناشناخته زیر /v1/:

{"detail": "Not Found"}

برای رفع، نماد را با GET /v1/instruments?q=… یا صندوق را با GET /v1/funds?q=… جست‌وجو کنید و ins_code یا reg_no نتیجه را به کار ببرید. نماد فارسی باید دقیق باشد؛ ref جست‌وجوی جزئی نمی‌کند.

پاسخ 422 چه شکلی دارد؟

422 دو شکل دارد. برای تاریخ نامعتبر، detail یک رشته است:

{"detail": "bad date 'bad': use YYYY-MM-DD, YYYYMMDD or Jalali 1403-01-15"}

برای بقیهٔ خطاهای اعتبارسنجی (نوع نادرست، پارامتر الزامیِ جاافتاده، مقدار بیرون از بازه)، detail فهرستی از خطاهاست و loc نام پارامتر را می‌گوید:

{
  "detail": [
    {
      "type": "less_than_equal",
      "loc": ["query", "limit"],
      "msg": "Input should be less than or equal to 5000",
      "input": "9999",
      "ctx": {"le": 5000}
    }
  ]
}

{
  "detail": [
    {"type": "missing", "loc": ["query", "start"], "msg": "Field required", "input": null},
    {"type": "missing", "loc": ["query", "end"], "msg": "Field required", "input": null}
  ]
}

پس در کد خود detail را هم به شکل رشته و هم به شکل فهرست بپذیرید.

برای 429 چطور درست دوباره تلاش کنم؟

به اندازهٔ سرآیند Retry-After صبر کنید و یک بار دیگر بفرستید. این همان تابع get است که در همهٔ نمونه‌های پایتون این مستندات می‌بینید:

import os
import time

import requests

BASE = "https://poolick.ir"
HEADERS = {"Authorization": f"Bearer {os.environ['ROSHA_KEY']}"}


def get(path, **kwargs):
    """GET with one retry on 429, waiting as long as Retry-After says."""
    for _ in range(2):
        r = requests.get(BASE + path, headers=HEADERS, timeout=30, **kwargs)
        if r.status_code != 429:
            break
        time.sleep(int(r.headers.get("Retry-After", "1")))
    r.raise_for_status()
    return r.json()


print(get("/v1/instruments/IRO1FOLD0001/daily", params={"limit": 1})["rows"])

معادل جاوااسکریپت در جاوااسکریپت است.

احتیاط

برای quota_exceeded مقدار Retry-After برابر ۳۶۰۰ ثانیه است و تلاش مجدد پیش از نیمه‌شب تهران نتیجه نمی‌دهد. در کارهای دسته‌ای، code را بخوانید و با دیدن quota_exceeded کار را متوقف کنید.

چطور در کد بر اساس code تصمیم بگیرم؟

بدنهٔ پاسخ را بخوانید و code را با مقدارهای جدول بالا مقایسه کنید. این برنامه یک درخواست می‌فرستد و برای هر دسته خطا پیام مشخصی می‌دهد:

import os
import sys

import requests

BASE = "https://poolick.ir"
HEADERS = {"Authorization": f"Bearer {os.environ['ROSHA_KEY']}"}

r = requests.get(
    BASE + "/v1/instruments/IRO1FOLD0001/quote", headers=HEADERS, timeout=30
)
if r.ok:
    print(r.json())
    sys.exit(0)

body = r.json()
code = body.get("code")  # present on 401, 403 and 429 only
if code == "rate_limited":
    sys.exit(f"wait {r.headers['Retry-After']} s, then retry")
if code == "quota_exceeded":
    sys.exit("daily quota used up: stop until midnight Asia/Tehran")
if code == "plan_forbids":
    sys.exit("this endpoint is not in your plan: " + body["detail"])
if r.status_code in (401, 403):
    sys.exit(f"access problem ({code}): fix the key or the subscription")
sys.exit(f"{r.status_code}: {body['detail']}")  # 404 or 422

خطاها در MCP چطور برمی‌گردند؟

خطاهای دسترسی در /mcp همان پاسخ‌های HTTP بالا هستند (401، 403 و 429 با همان code). خطاهای داده به شکل خطای ابزار (tool error) با متنی برمی‌گردند که راه رفع را پیشنهاد می‌کند. شرح در ابزارهای MCP است.

اگر مشکل حل نشد

برای پشتیبانی این چهار مورد را بفرستید: پیشوند کلید (مثل rosha_xxxxxxxx، هرگز کلید کامل)، نشانی کامل درخواست، زمان آن، و کد وضعیت با متن پاسخ. وضعیت لحظه‌ای سرویس در وضعیت سرویس است.