خطاها#

API از کودهای وضعیت متعارف HTTP و یک قالب خطای کوچک JSON استفاده می‌کند. شکست‌های احراز هویت و سهمیه {"error":{"code":"...","message":"..."}} را برمی‌گردانند؛ رکوردهای جزئیات غایب از یک شکل تودرتو استفاده می‌کنند که کلید error را درون شیء هم تکرار می‌کند.

همیشه اول وضعیت HTTP را بررسی کنید، سپس error.code را بخوانید.

قالب‌های خطا#

استاندارد#

{
  "error": {
    "code": "api_ability_denied",
    "message": "This credential is not permitted to perform the requested operation."
  }
}

رکورد جزئیات غایب#

{
  "error": {
    "error": "not_found",
    "message": "Sale not found."
  }
}

اعتبارسنجی#

شکست‌های اعتبارسنجی از شکل فریم‌ورک پیروی می‌کنند: یک message به‌اضافه یک شیء errors کلیدشده بر اساس فیلد.

{
  "message": "The given data was invalid.",
  "errors": {
    "to": [
      "The to field must be a date after or equal to from."
    ]
  }
}

کودهای وضعیت#

مرجع کودها#

شکست‌های سطح ابزار درون MCP ممکن است به‌جای خطای HTTP یک پیام خطا برگردانند؛ به عیب‌یابی MCP مراجعه کنید.

خطاهای محدودیت نرخ#

{
  "error": {
    "code": "api_burst_limit_exceeded",
    "message": "Too many API requests in a short period.",
    "retry_after_seconds": 17
  }
}

{
  "error": {
    "code": "api_quota_exceeded",
    "message": "The API request quota has been reached.",
    "scope": "user",
    "period": "day",
    "limit": 200,
    "used": 200,
    "reset_at": "2026-11-01T00:00:00+04:30",
    "retry_after_seconds": 18234
  }
}

هر دو یک هدر پاسخ Retry-After دربر دارند. هدر را رعایت کنید به‌جای یک توقف ثابت.

استراتژی تلاش دوباره#

تلاش دوباره برای یک خطای اجازه‌دهی فقط سهمیه را مصرف می‌کند. به‌جای آن آن را log کنید و هشدار دهید.

توصیه لاگ‌برداری#

• نام نقطه پایانی، وضعیت، error.code و شناسه درخواست را اگر پروکسی‌تان ارائه می‌کند log کنید.
• هرگز توکن حامل یا راز را log نکنید.
• شکست‌ها را با کارت مصرف اعتبارنامه در تنظیمات همبسته کنید.
• 403های مکرر از یک اعتبارنامه را به‌عنوان پسرفت اجازه‌ها در سیستم مبدأ تلقی کنید.

صفحات مرتبط#

• احراز هویت
• محدودیت‌های نرخ و سهمیه‌ها
• شروع سریع
• عیب‌یابی MCP