The API returns a PNG on success and a JSON error object on failure. Check the HTTP status before treating a response as an image.
Common responses
| Status | Meaning | What to do |
|---|---|---|
| 400 | Invalid XYZ path or more than one credential was supplied. | Check the URL template, coordinates, and authentication parameter. |
| 401 | The API key is missing or not permitted. | Use the active key shown once at issuance. Rotate it in Dashboard if it was lost. |
| 404 | The tile is unavailable, outside the supported native zoom range, or not present. | Check Coverage and the supported zoom range. |
| 405 | The HTTP method is not supported. | Use GET for tile requests. |
| 429 | A rate limit or the subscription Hard Limit was reached. | Honor Retry-After when present. Check Dashboard → Usage and the Hard Limit / Overage setting. |
| 500 / 503 | The service could not process the request. | Retry with backoff. If it continues, use Contact without sending your API key. |
Machine-readable body
{
"error": {
"code": "AUTHENTICATION_REQUIRED",
"message": "A valid first-party token or external API key is required"
}
}Error codes such as INVALID_TILE_PATH, ZOOM_NOT_AVAILABLE, CREDENTIAL_REJECTED, RATE_LIMITED, HARD_LIMIT_REACHED, and TILE_NOT_FOUND are stable enough for logging and troubleshooting. Do not include the API key in logs or support requests.