Maps Static API ممکن است زمانی که مشکلی پیش می‌آید خطا یا هشداری صادر کند. این راهنما هر پیام خطا را توضیح می‌دهد و دستورالعمل‌های بیشتری برای رفع خطاها ارائه می‌دهد.
درخواست های نامعتبر
در صورت درخواست نامعتبر، Maps Static API یک کد وضعیت HTTP 4xx و پیامی که مشکل را توصیف می‌کند، برمی‌گرداند. در زیر نمونه هایی از چنین شرایط خطا آورده شده است. توجه: این لیست کاملی از خطاهای احتمالی نیست. لطفاً کد خطای واقعی و پیام بازگردانده شده توسط API را برای جزئیات مشکلات خاص بررسی کنید.
| مثال شرط خطا | کد وضعیت |
|---|---|
درخواست شامل یک پارامتر نامعتبر است یا یک پارامتر مورد نیاز وجود ندارد. به عنوان مثال، پارامتر size در محدوده مورد انتظار مقادیر عددی نیست یا در درخواست وجود ندارد. | 400 BAD REQUEST |
| کلید API موجود در درخواست نامعتبر است. | 403 FORBIDDEN |
خطاهایی که از نمایش نقشه جلوگیری می کند
اگر درخواست معتبر است، اما خطای دیگری رخ می دهد که از نمایش نقشه جلوگیری می کند، Maps Static API بسته به خطا، متن یا تصویر خطا را به جای نقشه برمی گرداند. یک مثال از چنین شرایط خطا زمانی است که برنامه از محدودیت های استفاده خود فراتر رود. 
خطاهای مربوط به کلیدهای API و صورتحساب
اگر از Maps Static API بدون کلید API استفاده می‌کنید، یا اگر صورتحساب در حساب شما فعال نباشد، صفحه به جای نقشه یک تصویر خطا را با پیوندی نشان‌دهنده نوع خطا نشان می‌دهد. به عنوان مثال "g.co/staticmaperror/key".
| خطاها و راه حل های بدون کلید | |
|---|---|
 | شما از Maps Static API بدون کلید API استفاده می کنید. برای حل، شما باید: |
 | درخواست شما فاقد امضای دیجیتال است (الزامی). برای حل، URL خود را امضا کنید |
هشدارها
برای برخی از شرایط خطا، API یک نقشه را برمی‌گرداند اما ممکن است برخی از اطلاعات در نقشه گم شده باشد. هنگامی که این اتفاق می افتد، دو شرط برای اطلاع شما از هشدار رخ می دهد.
- یکی، نقشه نمایش داده می شود، اما با یک نوار خطای زرد رنگ که در بالای نقشه با متن "خطای نقشه: g.co/staticmaperror" قرار گرفته است.
- دوم، API اخطاری را در قالب یک هدر HTTP به نام
X-Staticmap-API-Warningبرمی‌گرداند.
به عنوان مثال، URL زیر حاوی یک مقدار غیرمنتظره در پارامتر markers است:
https://maps.googleapis.com/maps/api/staticmap?center=Williamsburg,Brooklyn,NY&zoom=13&scale=1&size=400x400&markers=sdgaags&key=YOUR_API_KEY
API یک نقشه را برمی‌گرداند، اما یک نوار خطای زرد رنگ را با «خطای نقشه: g.co/staticmaperror» روی تصویر نشان می‌دهد:
API همچنین هدر HTTP زیر را برمی گرداند:
X-Staticmap-API-Warning:Error geocoding: marker 1
جدول زیر هشدارهایی را توضیح می دهد که API ممکن است به عنوان هدر HTTP صادر کند:
هشدارها در هدرهای X-Staticmap-API-Warning | |
|---|---|
Error geocoding: [center, ][marker #number, ][visible #num, ][path #num, ]* | هنگام تلاش برای کدگذاری جغرافیایی درخواست، خطایی روی داد. انواع مختلفی از این پیام وجود دارد، بسته به عنصری که در آن کدگذاری جغرافیایی شکست خورده است (مرکز، نشانگر، قابل مشاهده یا مسیر) و تعداد عناصر شکست خورده. یکی از نمونه های این هشدار X-Staticmap-API-Warning:Error geocoding: marker 1 است، همانطور که در مثال بالا نشان داده شده است. |
Too many geocoded markers requested (max is 15). | این درخواست بیش از حداکثر مجاز تعداد نشانگرها با آدرس قابل خواندن توسط انسان را مشخص می کند. حداکثر 15 است. توجه داشته باشید که این محدودیت فقط برای نشانگرهایی اعمال می شود که به عنوان یک آدرس قابل خواندن برای انسان مشخص شده اند و نیاز به کدگذاری جغرافیایی دارند. برای نشانگرهای مشخص شده با مختصات طول و عرض جغرافیایی اعمال نمی شود. |
Too many geocoded polyline vertices requested (max is 15). | این درخواست بیش از حداکثر مجاز تعداد چند خط با آدرس قابل خواندن توسط انسان را مشخص می کند. حداکثر 15 است. توجه داشته باشید که این محدودیت فقط برای چند خطوط با رئوس مشخص شده به عنوان آدرس های قابل خواندن توسط انسان که نیاز به کدگذاری جغرافیایی دارند اعمال می شود. برای چند خط مشخص شده با مختصات طول و عرض جغرافیایی اعمال نمی شود. |
می‌توانید اخطارهای هدر HTTP را در کنسول Chrome DevTools ، کنسول وب فایرفاکس یا سایر ابزارهای مشابه در مرورگر خود مشاهده کنید.