Base URL, Headers, Errors

مبانی و احراز هویت

قواعد مشترک همه درخواست ها: آدرس پایه، هدرها، Bearer token و قالب خطا.

آدرس پایه

آدرس نهایی API برای تولید:

https://api.navidaa.ir

هدرها

هدر	وضعیت	توضیح
`Authorization`	ضروری	به شکل `Bearer <api-key>`.
`Content-Type`	برای POST ضروری	همیشه `application/json`.
`Idempotency-Key`	فقط ارسال	برای جلوگیری از ارسال تکراری OTP هنگام retry.

کلید API

کلید live با endpoint های live کار می کند. کلید تست با endpoint های سندباکس کار می کند. اگر نوع کلید با endpoint سازگار نباشد، پاسخ 403 با کد test_key_not_allowed یا live_key_not_allowed برمی گردد.

قالب خطا

{
  "error": {
    "code": "validation_error",
    "message": "Request validation failed",
    "details": {
      "errors": []
    }
  },
  "request_id": "..."
}

در کدهای قدیمی route ممکن است خطا داخل route به شکل ساده ساخته شود، اما exception handler آن را به همین envelope تبدیل می کند.

کدهای رایج

کد	HTTP	معنا
`unauthenticated`	401	کلید API ارسال نشده، نامعتبر، منقضی یا revoke شده است.
`validation_error`	422	بدنه یا path request با schema سازگار نیست.
`quota_exceeded`	429	سهمیه ماهانه پلن رایگان تمام شده است.
`insufficient_balance`	402	موجودی کیف پول برای verification کافی نیست.
`too_many_requests_phone_hour`	429	محدودیت ساعتی همان شماره فعال شده است.
`too_many_requests_phone_day`	429	محدودیت روزانه همان شماره فعال شده است.
`too_many_requests_api_key`	429	محدودیت دقیقه ای کلید API فعال شده است.