StardDevelopersداشبورد

خطاها

همه‌ی خطاها قالب یکسان JSON دارند با type، code، message، param و request_id؛ روی code تصمیم بگیر، نه message.

قالب خطا

نمونه — 400
{
  "error": {
    "type": "invalid_request_error",
    "code": "parameter_invalid",
    "message": "حداقل خرید استارز ۵۰ عدد است.",
    "param": "quantity",
    "request_id": "req_XZV2dfm7YHW6ECeAA1bW"
  }
}

code پایدار است و برای منطق برنامه است؛ message فارسی و برای نمایش است و ممکن است تغییر کند. request_id را در لاگ خودت نگه دار؛ پشتیبانی با آن درخواست را دقیق پیدا می‌کند.

کدهای HTTP

HTTPtypeمعنی
400invalid_request_errorپارامتر یا بدنه نامعتبر
401authentication_errorمشکل کلید
402payment_errorموجودی کافی نیست
403permission_errorscope یا وضعیت حساب
404invalid_request_errorپیدا نشد (منابع دیگران هم همیشه 404 می‌دهند)
409conflict_errorتداخل وضعیت یا idempotency
429rate_limit_errorمحدودیت نرخ
5xxapi_errorخطای سرور؛ با همان Idempotency-Key دوباره بفرست

کی دوباره تلاش کنم؟

روی 429 بعد از Retry-After، روی 5xx و قطعی شبکه با فاصله‌ی افزایشی (۱، ۲، ۴، ۸ ثانیه). درخواست‌های POST را فقط با Idempotency-Key تکرار کن. روی 4xx دیگر تکرار نکن؛ درخواست را اصلاح کن.