Sử dụng bộ sưu tập để sắp xếp ngăn nắp các trang
Lưu và phân loại nội dung dựa trên lựa chọn ưu tiên của bạn.
Maps Static API có thể đưa ra lỗi hoặc cảnh báo khi có sự cố. Hướng dẫn này giải thích từng thông báo lỗi và cung cấp thêm
hướng dẫn khắc phục lỗi.
Số yêu cầu không hợp lệ
Trong trường hợp yêu cầu không hợp lệ, Maps Static API sẽ trả về
mã trạng thái HTTP 4xx và thông báo mô tả
vấn đề. Dưới đây là ví dụ về các điều kiện lỗi như vậy. Lưu ý: Đây không phải là
danh sách đầy đủ các lỗi có thể xảy ra. Vui lòng kiểm tra mã lỗi thực tế
và thông báo do API trả về để cung cấp thông tin chi tiết về các vấn đề cụ thể.
Ví dụ về điều kiện lỗi
Mã trạng thái
Yêu cầu có một tham số không hợp lệ hoặc thiếu một tham số bắt buộc. Ví dụ: tham số size không nằm trong phạm vi
phạm vi giá trị số mong đợi hoặc bị thiếu trong yêu cầu.
400 BAD REQUEST
Khoá API trong yêu cầu không hợp lệ.
403 FORBIDDEN
Lỗi ngăn không cho hiển thị bản đồ
Nếu yêu cầu hợp lệ nhưng một lỗi khác xảy ra khiến bản đồ không hiển thị, thì API tĩnh của Maps sẽ trả về văn bản hoặc hình ảnh lỗi thay vì bản đồ, tuỳ thuộc vào lỗi. Ví dụ về điều kiện lỗi như vậy là khi ứng dụng vượt quá giới hạn sử dụng.
Hình: Hình ảnh lỗi được hiển thị thay vì bản đồ
Lỗi liên quan đến khoá API và quy trình thanh toán
Nếu bạn sử dụng API Maps Static mà không có khoá API hoặc nếu tính năng thanh toán không được bật trên tài khoản của bạn, thì trang sẽ hiển thị hình ảnh lỗi thay vì bản đồ, kèm theo đường liên kết cho biết loại lỗi. Ví dụ: "g.co/staticmaperror/key".
Lỗi không dùng chìa khoá và giải pháp
Bạn đang sử dụng Maps Static API mà không có khoá API. Người nhận
phân giải, bạn phải:
Yêu cầu của bạn thiếu chữ ký số (bắt buộc). Để giải quyết, hãy ký URL của bạn
Cảnh báo
Đối với một số điều kiện lỗi, API sẽ trả về một bản đồ nhưng có thể bản đồ đó bị thiếu một số thông tin. Khi điều này xảy ra, có hai điều kiện xảy ra để cho bạn biết
cảnh báo.
Một là bản đồ hiển thị, nhưng có một thanh lỗi màu vàng chồng lên đầu bản đồ với văn bản "Lỗi bản đồ: g.co/staticmaperror".
Thứ hai, API này trả về một cảnh báo trong
dưới dạng tiêu đề HTTP có tên X-Staticmap-API-Warning.
Ví dụ: URL sau đây chứa một giá trị không mong muốn trong tham số markers:
Đã xảy ra lỗi khi cố gắng mã hoá địa lý yêu cầu. Có
nhiều biến thể của thông báo này, tuỳ thuộc vào phần tử mà mã hoá địa lý
không thành công (trung tâm, điểm đánh dấu, hiển thị hoặc đường dẫn) và số lượng phần tử
không thành công. Một ví dụ về cảnh báo này là X-Staticmap-API-Warning:Error geocoding: marker 1, như trong ví dụ trên.
Too many geocoded markers requested (max is 15).
Yêu cầu chỉ định nhiều hơn số lượng điểm đánh dấu tối đa được phép
có địa chỉ mà con người có thể đọc được. Số lượng tối đa là 15. Xin lưu ý rằng giới hạn này chỉ áp dụng cho các điểm đánh dấu được chỉ định là địa chỉ mà con người đọc được và yêu cầu mã hoá địa lý. Phương thức này không áp dụng cho các điểm đánh dấu được chỉ định bằng tọa độ vĩ độ/kinh độ.
Too many geocoded polyline vertices requested (max is 15).
Yêu cầu chỉ định nhiều hơn số lượng hình nhiều đường tối đa cho phép
có địa chỉ mà con người có thể đọc được. Tối đa là 15. Lưu ý rằng giới hạn này
chỉ áp dụng cho hình nhiều đường có đỉnh được chỉ định là địa chỉ mà con người có thể đọc được
cần phải mã hoá địa lý. Phương thức này không áp dụng cho các đa tuyến được chỉ định bằng tọa độ vĩ độ/kinh độ.
[[["Dễ hiểu","easyToUnderstand","thumb-up"],["Giúp tôi giải quyết được vấn đề","solvedMyProblem","thumb-up"],["Khác","otherUp","thumb-up"]],[["Thiếu thông tin tôi cần","missingTheInformationINeed","thumb-down"],["Quá phức tạp/quá nhiều bước","tooComplicatedTooManySteps","thumb-down"],["Đã lỗi thời","outOfDate","thumb-down"],["Vấn đề về bản dịch","translationIssue","thumb-down"],["Vấn đề về mẫu/mã","samplesCodeIssue","thumb-down"],["Khác","otherDown","thumb-down"]],["Cập nhật lần gần đây nhất: 2025-09-04 UTC."],[[["\u003cp\u003eThe Maps Static API returns errors as HTTP status codes or warning messages for invalid requests, usage limits, or issues with API keys and billing.\u003c/p\u003e\n"],["\u003cp\u003eErrors that prevent map display can result in error images or text messages instead of the map, with details provided in the response.\u003c/p\u003e\n"],["\u003cp\u003eWarnings about potential issues, like geocoding problems or marker limits, are indicated by a yellow error bar on the map and HTTP header warnings.\u003c/p\u003e\n"],["\u003cp\u003eFor invalid requests, refer to the HTTP status code (e.g., 400, 403) and message for details about the specific issue.\u003c/p\u003e\n"],["\u003cp\u003eAlways check for HTTP header warnings and the yellow error bar to ensure your map is displayed correctly and address potential issues.\u003c/p\u003e\n"]]],[],null,["# Error Messages in Maps Static API\n\nThe Maps Static API may issue an error or warning when something goes\nwrong. This guide explains each error message, and provides further\ninstructions for resolving errors.\n\nInvalid requests\n----------------\n\nIn the case of an invalid request, the Maps Static API returns\nan HTTP `4xx` status code and a message describing the\nproblem. Below are examples of such error conditions. Note: This is not\na complete list of the possible errors. Please check the actual error code\nand message returned by the API for details of specific problems.\n\n| Example of error condition | Status code |\n|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------|\n| The request includes an invalid parameter, or a required parameter is missing. For example, the `size` parameter is not within the expected range of numeric values, or is missing from the request. | `400 BAD REQUEST` |\n| The API key included in the request is invalid. | `403 FORBIDDEN` |\n\nErrors that prevent a map from being displayed\n----------------------------------------------\n\nIf the request is valid, but another error occurs that prevents the map from\nbeing displayed, the Maps Static API returns either text or an error\nimage instead of the map, depending on the error. An example of such an error\ncondition is when the application exceeds its\n[usage limits](/maps/documentation/maps-static/usage-limits).\n\nFigure: An error image displayed instead of a map\n\n### Errors related to API keys and billing\n\nIf you use the Maps Static API without an API key, or if billing\nis not enabled on your account, the page displays an error image instead of a\nmap, with a link indicating the type of error. For example\n\"g.co/staticmaperror/key\".\n\n| Keyless errors and solutions ||\n|---|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| | You are using the Maps Static API without an API key. To resolve, you must: 1. [Get an API key](/maps/documentation/maps-static/get-api-key#get-an-api-key) 2. [Enable billing](https://console.cloud.google.com/project/_/billing/enable?utm_source=Docs_BillingNudge) 3. [Sign your URL](/maps/documentation/maps-static/get-api-key#digital-signature) |\n| | Your request is missing a digital signature (required). To resolve, [Sign your URL](/maps/documentation/maps-static/get-api-key#digital-signature) |\n\nWarnings\n--------\n\nFor some error conditions, the API returns a map but some information may\nbe missing from the map. When this happens, two conditions occur to inform you of\nthe warning.\n\n- One, the map displays, but with a yellow error bar superimposed over top of the map with the text \"Map error: g.co/staticmaperror\".\n- Two, the API returns a warning in the form of an HTTP header named `X-Staticmap-API-Warning`.\n\nFor example, the following URL contains an unexpected value in the\n`markers` parameter: \n\n```\nhttps://maps.googleapis.com/maps/api/staticmap?center=Williamsburg,Brooklyn,NY&zoom=13&scale=1&size=400x400&markers=sdgaags&key=YOUR_API_KEY\n```\n\nThe API returns a map, but displays a yellow error bar superimposed\nover the image with \"Map error: g.co/staticmaperror\":\n\nThe API also returns the following HTTP header: \n\n```\nX-Staticmap-API-Warning:Error geocoding: marker 1\n```\n\nThe following table describes the warnings that the API may issue as HTTP\nheaders:\n\n| Warnings in `X-Staticmap-API-Warning` headers ||\n|-------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| `Error geocoding: [center, ][marker #number, ][visible #num, ][path #num, ]*` | An error occurred while attempting to geocode the request. There are many variants of this message, depending on the element where geocoding failed (center, marker, visible, or path) and the number of elements that failed. One example of this warning is `X-Staticmap-API-Warning:Error geocoding: marker 1`, as shown in the above example. |\n| `Too many geocoded markers requested (max is 15).` | The request specifies more than the allowed maximum number of markers with a human readable address. The maximum is 15. Note that this limit applies only to markers specified as a human-readable address that requires geocoding. It does not apply to markers specified with latitude/longitude coordinates. |\n| `Too many geocoded polyline vertices requested (max is 15).` | The request specifies more than the allowed maximum number of polylines with a human readable address. The maximum is 15. Note that this limit applies only to polylines with vertices specified as human-readable addresses that require geocoding. It does not apply to polylines specified with latitude/longitude coordinates. |\n\nYou can see the HTTP header warnings in the\n[Chrome DevTools Console](/web/tools/chrome-devtools/console/console-write#errors_and_warnings), the\n[Firefox\nWeb Console](https://developer.mozilla.org/en-US/docs/Tools/Web_Console), or other equivalent tools in your browser.\n| **Note:** You should check for HTTP header warnings if you notice the yellow error bar on the map indicating that something may be missing from the map. It's also a good idea to check for warnings before launching a new application. Consider also whether user input or internationalization could lead to unexpected characters or malformed latitude/longitude coordinate specifications in the request."]]
