Maps Static API는 무언가가 바뀔 때 오류 또는 경고를 표시할 수 있습니다.
오답입니다. 이 가이드에서는 각 오류 메시지를 설명하고 오류를 해결하기 위한 추가 안내를 제공합니다.
잘못된 요청
잘못된 요청의 경우 Maps Static API는 HTTP 4xx 상태 코드와 문제를 설명하는 메시지를 반환합니다. 아래는 이러한 오류 상황의 예를 보여줍니다. 참고: 이 목록은 가능한 오류의 전체 목록은 아닙니다. 실제 오류 코드를 확인하세요.
특정 문제에 대한 세부정보를 확인하기 위해 API에서 반환한 메시지를 확인할 수 있습니다.
오류 상황의 예
상태 코드
요청에 잘못된 매개변수가 포함되거나, 필요한 매개변수가 누락되었습니다. 예를 들어 size 매개변수는
숫자 값의 예상 범위이거나 요청에서 누락되었습니다.
400 BAD REQUEST
요청에 포함된 API 키가 잘못되었습니다.
403 FORBIDDEN
지도를 표시할 수 없는 오류
요청은 올바르지만 지도를 표시할 수 없는 또 다른 오류가 발생하면 Maps Static API는 오류에 따라 지도 대신 텍스트나 오류 이미지를 반환합니다. 이러한 오류의 예
애플리케이션이
사용량 제한을 검토하세요.
그림: 지도 대신 오류 이미지가 표시됨
API 키 및 결제와 관련된 오류
API 키 없이 Maps Static API를 사용하거나 계정에서 결제가 사용 설정되지 않은 경우 페이지에 지도 대신 오류 이미지가 오류 유형을 나타내는 링크와 함께 표시됩니다. 예를 들면 'g.co/staticmaperror/key'입니다.
키 없는 오류 및 해결 방법
API 키 없이 Maps Static API를 사용하고 있습니다. 이 문제를 해결하려면 다음 단계를 따르세요.
요청을 지오코딩하려는 중에 오류가 발생했습니다. 현재
지오코딩이 지오코딩이 필요한 요소에 따라
실패 (가운데, 마커, 표시 가능 또는 경로) 및 요소 수
확인할 수 있습니다 이 경고의 한 가지 예는 위 예에 표시된 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입니다. 참고로, 이 제한은 사람이 읽을 수 있는 주소(지오코딩이 필요한 주소)로 지정된 교점이 있는 폴리라인에만 적용됩니다. 인코더-디코더는
위도/경도 좌표입니다.
[null,null,["최종 업데이트: 2025-08-31(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."]]
