خطاها و محدودیت‌ها — مستندات

قالب خطا

{
  "error": {
    "code": "quota_exceeded",
    "message": "سهمیهٔ ماهانهٔ درخواست‌های شما تمام شده است.",
    "docs": "https://uttamap.ir/docs/errors#quota_exceeded"
  }
}

HTTP	code	معنی
400	`invalid_params`	پارامتر نادرست؛ فیلد `field` می‌گوید کدام
401	`missing_key`, `invalid_key`, `revoked_key`	کلید نیست، اشتباه است یا لغو شده
402	`insufficient_balance`	مازاد روشن است ولی کیف پول خالی است
403	`origin_not_allowed`	دامنه یا اپ در فهرست کلید عمومی نیست
403	`secret_key_in_browser`	کلید مخفی از مرورگر آمده
403	`service_not_allowed`, `ip_not_allowed`, `account_suspended`	محدودیت کلید یا حساب
413	`too_many_points`	بیش از ۲۵ نقطه یا ۶۲۵ جفت ماتریس
429	`rate_limited`	بیش از حد مجاز در ثانیه؛ هدر `Retry-After` را رعایت کنید
429	`quota_exceeded`, `daily_cap_reached`	سهمیهٔ ماه یا سقف روزانهٔ کلید تمام شده
502	`engine_error`	خطای موقت از سمت ما؛ از سهمیه کم نمی‌شود
503	`maintenance`	سرویس موقتاً در دسترس نیست

هدرهای پاسخ

هدر	معنی
`X-Uttamap-Request-Id`	شناسهٔ درخواست؛ در تیکت پشتیبانی بفرستید
`X-Uttamap-Data-Version`	نسخهٔ دادهٔ نقشه
`X-RateLimit-Limit` / `-Remaining` / `-Reset`	محدودیت نرخ ثانیه‌ای
`X-Uttamap-Quota-Remaining`	سهمیهٔ باقی‌ماندهٔ ماه

محدودیت نرخ

هر پلن سقف درخواست در ثانیه دارد: رایگان ۵، پایه ۱۰، استارتاپ ۲۵، حرفه‌ای ۶۰ و تجاری ۱۲۰. تایل‌ها سقف جدا و ۲۰ برابری دارند، چون یک صفحهٔ نقشه ده‌ها تایل هم‌زمان می‌خواهد.

بعد از تمام شدن سهمیه

در پلن رایگان، درخواست‌ها تا اول دورهٔ بعد 429 quota_exceeded می‌گیرند. در پلن‌های پولی اگر «پرداخت مازاد» روشن باشد، سرویس قطع نمی‌شود و هزینه از کیف پول کم می‌شود. در ۸۰ و ۱۰۰ درصد سهمیه در پیشخوان اعلان می‌آید.