خطاها

تمام خطاهای API عمومی یک Envelope ثابت و قابل پردازش توسط برنامه دارند. جزئیات داخلی، Stack Trace، Provider و Payload هسته در پاسخ مشتری قرار نمی‌گیرند.

نمونه Validation Error:

{
  "code": "validation_error",
  "message": "اطلاعات درخواست معتبر نیست.",
  "correlationId": "4ac56ce65f3f44fca4370761283a583c",
  "errors": {
    "recipient": [
      "شماره گیرنده معتبر نیست."
    ]
  }
}

فیلدها

فیلد	توضیح
`code`	کد پایدار برای تصمیم‌گیری برنامه
`message`	توضیح عمومی قابل نمایش/ثبت
`correlationId`	شناسه رهگیری درخواست برای پشتیبانی
`errors`	جزئیات Validation به تفکیک فیلد؛ در سایر خطاها ممکن است وجود نداشته باشد

HTTP Statusهای اصلی

Status	Code معمول	کاربرد
`400`	`validation_error` / `invalid_request`	پارامتر نامعتبر یا JSON/ساختار Request مخدوش
`401`	`invalid_api_key`	API Key معتبر نیست یا ارسال نشده است
`403`	`forbidden`	حساب برای عملیات موردنظر مجوز ندارد
`404`	`not_found`	منبع برای این حساب پیدا نشد
`409`	`conflict`	درخواست با وضعیت فعلی منبع سازگار نیست
`429`	`rate_limited`	Rate Limit عبور کرده است
`500`	`unexpected_error`	خطای غیرمنتظره در لایه عمومی
`502`	`upstream_error`	پاسخ ناسازگار از هسته داخلی دریافت شده است
`503`	`service_unavailable`	وابستگی داخلی موقتاً در دسترس نیست

برنامه مشتری بهتر است ابتدا بر اساس HTTP Status و سپس code تصمیم بگیرد و به متن message وابسته نشود.

Correlation ID

همان مقدار correlationId در Header پاسخ نیز برگردانده می‌شود:

X-Correlation-Id: 4ac56ce65f3f44fca4370761283a583c

برای پیگیری خطای عملیاتی، correlationId را همراه زمان تقریبی درخواست و در صورت وجود trackingCode به پشتیبانی اعلام کنید. API Key یا متن حساس پیام را برای عیب‌یابی ارسال نکنید.