Mit Sammlungen den Überblick behalten
Sie können Inhalte basierend auf Ihren Einstellungen speichern und kategorisieren.
Die Maps Static API kann einen Fehler oder eine Warnung ausgeben, wenn etwas
falsch. In diesem Leitfaden werden die einzelnen Fehlermeldungen erläutert und es werden weitere Schritte zur Fehlerbehebung beschrieben.
Unzulässige Anforderungen
Bei einer ungültigen Anfrage gibt die Maps Static API
Ein HTTP-Statuscode 4xx und eine Nachricht mit einer Beschreibung der
Problem. Nachstehend finden Sie Beispiele für die Fehlerbedingungen. Hinweis: Dies ist keine vollständige Liste der möglichen Fehler. Überprüfe den tatsächlichen Fehlercode.
und eine Nachricht, die von der API zurückgegeben wird, um Details zu bestimmten Problemen zu erhalten.
Beispiel: Fehlerbedingung
Statuscode
Die Anfrage enthält einen ungültigen Parameter oder einen fehlenden erforderlichen Parameter. Beispielsweise liegt der Parameter size nicht im erwarteten Bereich der numerischen Werte oder fehlt in der Anfrage.
400 BAD REQUEST
Der in der Anforderung enthaltene API-Schlüssel ist ungültig.
403 FORBIDDEN
Fehler, die das Anzeigen einer Karte verhindern
Wenn die Anfrage gültig ist, aber ein anderer Fehler auftritt, der die Anzeige der Karte verhindert, gibt die Maps Static API je nach Fehler entweder Text oder ein Fehlerbild zurück. Ein Beispiel für einen solchen Fehler
Bedingung ist, wenn die Anwendung ihre
Nutzungslimits.
Abbildung: Ein Fehlerbild wird anstelle einer Karte angezeigt
Fehler im Zusammenhang mit API-Schlüsseln und Abrechnung
Wenn Sie die Maps Static API ohne API-Schlüssel verwenden oder die Abrechnung
nicht aktiviert ist, wird auf der Seite ein Fehlerbild statt eines
-Karte mit einem Link, der den Fehlertyp angibt. Beispiel: „g.co/staticmaperror/key“.
Schlüssellose Fehler und Lösungen
Sie verwenden die Maps Static API ohne API-Schlüssel. Bis
beheben, müssen Sie:
In Ihrer Anfrage fehlt eine digitale Signatur (erforderlich). Um das Problem zu beheben,
URL signieren
Warnungen
Bei einigen Fehlerbedingungen gibt die API eine Karte zurück. Einige Informationen können jedoch
auf der Karte fehlen. In diesem Fall werden Sie auf zwei Arten über die Warnung informiert.
Erstens wird die Karte angezeigt, allerdings mit einer gelben Fehlerleiste,
oben auf der Karte mit dem Text „Map error: g.co/staticmaperror“.
Zweitens: Die API gibt eine Warnung in Form eines HTTP-Headers mit dem Namen X-Staticmap-API-Warning zurück.
Die folgende URL enthält beispielsweise einen unerwarteten Wert im
markers-Parameter:
Bei dem Versuch, das Geocoding für die Anforderung auszuführen, ist ein Fehler aufgetreten. Es gibt
viele Varianten dieser Nachricht, abhängig von dem Element, bei dem die Geocodierung
fehlgeschlagen (center, Markierung, sichtbar oder Pfad) und die Anzahl der Elemente
der fehlgeschlagen ist. Ein Beispiel für diese Warnung ist
X-Staticmap-API-Warning:Error geocoding: marker 1, als
wie im obigen Beispiel dargestellt.
Too many geocoded markers requested (max is 15).
In der Anfrage wird mehr als die maximal zulässige Anzahl von Markierungen angegeben.
mit einer visuell lesbaren Adresse. Der Maximalwert beträgt 15. Beachten Sie, dass dieses Limit
gilt nur für Markierungen, die als visuell lesbare Adresse
erfordert Geocoding. Sie gilt nicht für Markierungen, die mit
Längen- und Breitengrade angeben.
Too many geocoded polyline vertices requested (max is 15).
In der Anfrage ist eine größere Anzahl von Polylinien mit einer visuell lesbaren Adresse angegeben als zulässig. Der Maximalwert beträgt 15. Beachten Sie, dass dieses Limit
gilt nur für Polylinien mit Scheitelpunkten, die als für Menschen lesbare Adressen angegeben sind,
Geocoding ist erforderlich. Sie gilt nicht für Polylinien, die mit Breiten- und Längengradkoordinaten angegeben sind.
[[["Leicht verständlich","easyToUnderstand","thumb-up"],["Mein Problem wurde gelöst","solvedMyProblem","thumb-up"],["Sonstiges","otherUp","thumb-up"]],[["Benötigte Informationen nicht gefunden","missingTheInformationINeed","thumb-down"],["Zu umständlich/zu viele Schritte","tooComplicatedTooManySteps","thumb-down"],["Nicht mehr aktuell","outOfDate","thumb-down"],["Problem mit der Übersetzung","translationIssue","thumb-down"],["Problem mit Beispielen/Code","samplesCodeIssue","thumb-down"],["Sonstiges","otherDown","thumb-down"]],["Zuletzt aktualisiert: 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."]]
