Thông báo lỗi trong API tĩnh của Maps

API tĩnh của Maps 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 các hướng dẫn khác để 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ệ, API tĩnh của Maps sẽ trả về mã trạng thái HTTP 4xx và một 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 mà API trả về để biết 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 thông số không hợp lệ hoặc thiếu một thông số bắt buộc. Ví dụ: tham số size không nằm trong phạm vi giá trị số dự kiến 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 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 ngăn bản đồ 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ề tình trạng lỗi như vậy là khi ứng dụng vượt quá giới hạn sử dụng.

Hình ảnh lỗi xuất hiện thay cho bản đồ
Hình: Một hình ảnh lỗi xuất hiện thay vì bản đồ

Nếu bạn sử dụng API tĩnh của Maps mà không có khoá API hoặc nếu tính năng thanh toán không được bật trong 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 một đườ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
Lỗi giới hạn sử dụng: đã vượt quá giới hạn tải bản đồ hàng ngày được cung cấp Bạn đang sử dụng Maps Static API mà không có khoá API. Để giải quyết, bạn phải:
  1. Tải khoá API
  2. Bật tính năng thanh toán
  3. Ký URL của bạn
Lỗi về hạn mức sử dụng: URL yêu cầu thiếu chữ ký số Yêu cầu của bạn thiếu chữ ký số (bắt buộc). Để giải quyết vấn đề, 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ề bản đồ nhưng có thể thiếu một số thông tin trên bản đồ. Khi điều này xảy ra, có hai điều kiện để cho bạn biết về cảnh báo.

  • Một là bản đồ sẽ xuất hiện, nhưng có một thanh lỗi màu vàng được xếp chồng lên trên bản đồ cùng với nội dung "Lỗi bản đồ: g.co/staticmaperror".
  • Thứ hai, API sẽ trả về một cảnh báo dưới dạng tiêu đề HTTP có tên X-Staticmap-API-Warning.

Ví dụ: URL sau đây chứa giá trị không mong muốn trong tham số 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 trả về một bản đồ, nhưng hiển thị một thanh lỗi màu vàng được xếp chồng lên hình ảnh có "Lỗi bản đồ: g.co/staticmaperror":

Hiển thị bản đồ nhưng có lỗi Bản đồ: g.co/staticmaperror

API cũng trả về tiêu đề HTTP sau đây:

X-Staticmap-API-Warning:Error geocoding: marker 1

Bảng sau đây mô tả các cảnh báo mà API có thể đưa ra dưới dạng tiêu đề HTTP:

Cảnh báo trong tiêu đề X-Staticmap-API-Warning
Error geocoding: [center, ][marker #number, ][visible #num, ][path #num, ]* Đã xảy ra lỗi khi cố gắng mã hoá địa lý cho 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ử không mã hoá được vị trí địa lý (ở giữa, điểm đánh dấu, hiển thị hoặc đường dẫn) và số lượng phần tử không mã hoá được. Một ví dụ về cảnh báo này là X-Staticmap-API-Warning:Error geocoding: marker 1, như minh hoạ trong ví dụ trên.
Too many geocoded markers requested (max is 15). Yêu cầu này chỉ định nhiều hơn số điểm đánh dấu tối đa cho phép mà một địa chỉ mà con người có thể đọc được. 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 dưới dạng địa chỉ mà con người có thể đọc được và yêu cầu mã hoá địa lý. Thông số này không áp dụng cho các điểm đánh dấu được chỉ định bằng vĩ độ/kinh độ.
Too many geocoded polyline vertices requested (max is 15). Yêu cầu này chỉ định nhiều hơn số lượng nhiều dòng tối đa cho phép với địa chỉ mà con người có thể đọc được. Tối đa là 15. Xin lưu ý rằng giới hạn này chỉ áp dụng cho hình nhiều đường có các đỉnh được chỉ định là địa chỉ mà con người có thể đọc được và cần mã hoá địa lý. Giá trị này không áp dụng cho hình nhiều đường được chỉ định với vĩ độ/kinh độ.

Bạn có thể xem cảnh báo tiêu đề HTTP trong Bảng điều khiển dành cho nhà phát triển của Chrome, Bảng điều khiển web của Firefox hoặc các công cụ tương đương khác trong trình duyệt của mình.