La página Descripción general del transporte seguro tiene ejemplos de la línea de comandos de curl para usar ambas API, así como detalles de TLS y otras funciones comunes de DNS por TLS (DoT) y DoH.
El DNS público de Google no admite URLs http: no seguras para las llamadas a la API.
Métodos HTTP
GET
El uso del método GET puede reducir la latencia, ya que se almacena en caché de manera más eficaz.
Las solicitudes GET de RFC 8484 deben tener un parámetro de consulta ?dns= con un mensaje DNS codificado en Base64Url.
El método GET es el único método compatible con la API de JSON.
POST
El método POST solo es compatible con la API de RFC 8484 y usa un mensaje DNS binario con Application-Type/dns-message en el cuerpo de la solicitud y en la respuesta HTTP de DoH.
HEAD
En este momento, no se admite el encabezado HEAD y muestra un error 400 de Solicitud incorrecta.
Otros métodos muestran errores 501 Not Implemented.
Códigos de estado HTTP
El DoH del DNS público de Google muestra los siguientes códigos de estado HTTP:
Completado correctamente
200 OK
El análisis de HTTP y la comunicación con el agente de resolución de DNS se realizaron correctamente. El contenido del cuerpo de la respuesta es una respuesta DNS con codificación binaria o JSON, según el extremo de la consulta, el encabezado Aceptar y los parámetros GET.
Redirecciones
Movido permanentemente 301
Los clientes deben volver a intentarlo en la URL proporcionada en el encabezado Location:. Si la consulta original era una solicitud POST, los clientes solo deberían volver a intentarlo con GET si la URL nueva especifica un argumento de parámetro GET de dns; de lo contrario, los clientes deben volver a intentarlo con POST.
Es posible que se usen otros códigos, como 302 Encontrado, 307 Redireccionamiento temporal o 308 Redireccionamiento permanente, en el futuro, y los clientes de DoH deben manejar los cuatro códigos.
Las respuestas con los códigos 301 y 308 permanentes se deben almacenar en caché de forma indefinida y, si es posible, se les puede solicitar a los usuarios que actualicen su configuración original con la URL nueva.
Las solicitudes POST que obtienen respuestas 307 o 308 siempre se deben reintentar con POST.
Errores
Las respuestas de error incluirán una explicación del estado HTTP en el cuerpo, ya sea mediante HTML o texto sin formato.
400 Bad Request
Problemas para analizar los parámetros GET o un mensaje de solicitud de DNS no válido.
Para parámetros GET incorrectos, el cuerpo HTTP debe explicar el error. La mayoría de los mensajes DNS no válidos obtienen un valor de 200 OK con un FORMERR. El error de HTTP se muestra para los mensajes ilegibles sin sección Question, una marca QR que indica una respuesta u otras combinaciones de marcas sin sentido con errores de análisis de DNS binarios.
Carga útil 413 demasiado grande
El cuerpo de una solicitud POST de RFC 8484 supera el tamaño máximo de mensaje de 512 bytes.
URI 414 demasiado largo
El encabezado de la consulta GET era demasiado grande o el parámetro dns tenía un mensaje DNS codificado en Base64Url que excedía el tamaño máximo del mensaje de 512 bytes.
415 Unsupported Media Type
El cuerpo de la POST no tenía un encabezado de tipo de contenido application/dns-message.
429 Too Many Requests
El cliente envió demasiadas solicitudes en un período determinado. Los clientes deben dejar de enviar solicitudes hasta el momento especificado en el encabezado "reintentar-después" (un tiempo relativo en segundos).
500 Internal Server Error
Errores de DoH internos del DNS público de Google.
No implementado [501 Not Implemented]
Solo se implementan los métodos GET y POST. Los demás obtienen este error.
502 Bad Gateway
El servicio de DoH no pudo comunicarse con los agentes de resolución de DNS público de Google.
En el caso de una respuesta 502, aunque reintentar en una dirección de DNS público de Google alternativa podría ser útil, una respuesta de resguardo más eficaz sería probar otro servicio de DoH o cambiar a DNS UDP o TCP tradicional en 8.8.8.8.
Beneficios del DoH
El uso de HTTPS, no solo la encriptación TLS, tiene algunos beneficios prácticos:
Las API de HTTPS con amplia disponibilidad y compatibilidad simplifican la implementación tanto para el DNS público de Google como para los clientes potenciales.
Un servicio HTTPS proporciona a las apps web acceso a todos los tipos de registro DNS, lo que evita las limitaciones del navegador existente y las APIs de DNS del SO, que, por lo general, solo admiten las búsquedas de host a dirección.
Los clientes que implementan la compatibilidad con HTTPS basado en UDP en QUIC pueden evitar problemas como el bloqueo de cabeza de línea que puede ocurrir cuando se usa el transporte TCP.
Prácticas recomendadas de privacidad para el DoH
Los desarrolladores de aplicaciones de DoH deben tener en cuenta las prácticas recomendadas de privacidad que se describen en RFC 8484 y que se expanden a continuación:
Limita el uso de encabezados HTTP
Los encabezados HTTP revelan información sobre la implementación de DoH del cliente y se pueden usar para anular el anonimato de los clientes. Los encabezados como Cookie, User-Agent y Accept-Language son los elementos más infractores, pero incluso el conjunto de encabezados enviados puede ser revelador. Para minimizar este riesgo, envía solo los encabezados HTTP requeridos para el DoH: Host, Tipo de contenido (para POST) y, si es necesario, Aceptar.
El usuario-agente debe incluirse en todas las versiones de desarrollo o de prueba.
Usa opciones de relleno de EDNS
Sigue las instrucciones de RFC 8467 sobre el uso de opciones de relleno de EDNS para rellenar consultas de DoH con algunas longitudes comunes a fin de brindar protección contra el análisis de tráfico. También es posible usar padding HTTP/2, pero, a diferencia de padding de EDNS, no se generará padding en las respuestas de los servidores DoH.
Usa RFC 8484 POST solo para aplicaciones o modos de navegador sensibles a la privacidad.
El uso de POST para las consultas de DoH reduce la capacidad de almacenamiento en caché de las respuestas y puede aumentar la latencia de DNS, por lo que, generalmente, no se recomienda. Sin embargo, reducir el almacenamiento en caché es probablemente recomendable para aplicaciones sensibles a la privacidad, y podría proteger contra ataques de sincronización de apps web que intentan determinar qué dominios visitó el usuario últimamente.
[null,null,["Última actualización: 2025-07-25 (UTC)"],[[["\u003cp\u003eGoogle Public DNS offers two DoH APIs: \u003ccode\u003edns.google/dns-query\u003c/code\u003e (RFC 8484, GET & POST) and \u003ccode\u003edns.google/resolve\u003c/code\u003e (JSON API, GET only).\u003c/p\u003e\n"],["\u003cp\u003eDoH supports both IPv4 and IPv6 using HTTPS for enhanced security and wider accessibility.\u003c/p\u003e\n"],["\u003cp\u003eFor privacy, minimize HTTP headers, utilize EDNS padding, and consider RFC 8484 POST for sensitive applications.\u003c/p\u003e\n"],["\u003cp\u003eGoogle Public DNS returns various HTTP status codes, including 200 OK for success (check DNS response code for errors) and error codes like 400, 413, 414, 415, 429, 500, 501, and 502.\u003c/p\u003e\n"],["\u003cp\u003eDoH benefits include wider API support, access to all DNS record types for web apps, and potential performance improvements with QUIC.\u003c/p\u003e\n"]]],["Google Public DNS offers two DoH APIs: one using RFC 8484 (supporting GET and POST) and a JSON API (GET only). GET requests use Base64Url-encoded DNS messages in the query parameters; POST requests use binary DNS messages. The service returns standard HTTP status codes, including 200 OK for success, and various error codes (400, 413, 414, 415, 429, 500, 501, 502), with 301, 307, and 308 for redirection. Privacy best practices include limiting HTTP headers, using EDNS padding, and employing POST for sensitive applications.\n"],null,["# DNS-over-HTTPS (DoH)\n\nGoogle Public DNS provides two distinct DoH APIs at these endpoints:\n\n- https://dns.google/dns-query -- [RFC 8484](https://tools.ietf.org/html/rfc8484) (GET and POST)\n- https://dns.google/resolve? -- [JSON API](/speed/public-dns/docs/doh/json) (GET)\n\n| **Note:** There is also a human-friendly web interface at \u003chttps://dns.google/\u003e. This web app displays JSON results in a browser but does not implement an API; do not confuse its https://dns.google/query? URLs with the two API URLs.\n\nThe [Secure Transports Overview](/speed/public-dns/docs/secure-transports#doh)\npage has `curl` command line examples for using both APIs as well as details of\nTLS and other features common to both DNS over TLS (DoT) and DoH.\n\nDoH is also supported for the IPv6-only\n[Google Public DNS64 service](/speed/public-dns/docs/dns64#secure).\n\nGoogle Public DNS does not support insecure `http:` URLs for API calls.\n\nHTTP methods\n------------\n\nGET\n: Using the GET method can reduce latency, as it is cached more effectively.\n RFC 8484 GET requests must have a `?dns=` query parameter with a\n Base64Url encoded DNS message.\n The GET method is the only method supported for the JSON API.\n\nPOST\n: The POST method is only supported for the RFC 8484 API and uses a binary DNS\n message with Content-Type application/dns-message in the request body and in\n the DoH HTTP response.\n\nHEAD\n: *HEAD is not currently supported, and returns a 400 Bad Request error*.\n\nOther methods return 501 Not Implemented errors.\n\nHTTP status codes\n-----------------\n\nGoogle Public DNS DoH returns the following HTTP status codes:\n\n### Success\n\n200 OK\n: HTTP parsing and communication with DNS resolver was successful, and the\n response body content is a DNS response in either binary or JSON encoding,\n depending on the query endpoint, Accept header and GET parameters.\n| **Note:** An HTTP success may still be a DNS failure. Check the DNS response code (JSON \"Status\" field) for the DNS errors SERVFAIL, FORMERR, REFUSED, and NOTIMP.\n\n### Redirections\n\n301 Moved Permanently\n: Clients should retry at the URL provided in the `Location:` header. If the\n original query was a POST request, clients should only retry with GET if the\n new URL specifies a `dns` GET parameter argument; otherwise clients should\n retry with POST.\n\nOther codes such as 302 Found, 307 Temporary Redirect or 308 Permanent Redirect\nmay be used in the future, and DoH clients should handle all four codes.\n\nResponses with the permanent 301 and 308 codes should be cached indefinitely,\nand if practical, users may be prompted to update their original configuration\nusing the new URL.\n\nPOST requests that get 307 or 308 responses should always be retried with POST.\n\n### Errors\n\nError responses will have an explanation of the HTTP status in the body,\nusing either HTML or plain text.\n\n400 Bad Request\n: Problems parsing the GET parameters, or an invalid DNS request message.\n For bad GET parameters, the HTTP body should explain the error. Most invalid\n DNS messages get a 200 OK with a FORMERR; the HTTP error is returned for\n garbled messages with no Question section, a QR flag indicating a reply, or\n other nonsensical flag combinations with binary DNS parse errors.\n\n413 Payload Too Large\n: An RFC 8484 POST request body exceeded the 512 byte maximum message size.\n\n414 URI Too Long\n: The GET query header was too large or the `dns` parameter had a Base64Url\n encoded DNS message exceeding the 512 byte maximum message size.\n\n415 Unsupported Media Type\n: The POST body did not have an `application/dns-message` Content-Type header.\n\n429 Too Many Requests\n: The client has sent too many requests in a given amount of time. Clients\n should stop sending requests until the time specified in the Retry-After\n header (a relative time in seconds).\n\n500 Internal Server Error\n: Google Public DNS internal DoH errors.\n\n501 Not Implemented\n: Only GET and POST methods are implemented, other methods get this error.\n\n502 Bad Gateway\n: The DoH service could not contact Google Public DNS resolvers.\n\nIn the case of a 502 response, although retrying on an alternate Google Public\nDNS address might help, a more effective fallback response would be to try\nanother DoH service, or to switch to traditional UDP or TCP DNS at 8.8.8.8.\n\nBenefits of DoH\n---------------\n\nUsing HTTPS, not just TLS encryption, has some practical benefits:\n\n- Widely available and well-supported HTTPS APIs simplify implementation for both Google Public DNS itself and potential clients.\n- An HTTPS service provides web apps with access to all DNS record types, avoiding the limitations of existing browser and OS DNS APIs, which generally support only host-to-address lookups.\n- Clients that implement QUIC UDP-based HTTPS support can avoid problems like head-of-line blocking that can occur when using TCP transport.\n\nPrivacy Best Practices for DoH\n------------------------------\n\nDevelopers of DoH applications should consider the privacy best practices\noutlined in [RFC 8484](https://tools.ietf.org/html/rfc8484#section-8) and\nexpanded below:\n\n- Limit use of HTTP Headers\n\n HTTP headers reveal information about the client's DoH implementation and\n can be used to deanonymize clients. Headers like Cookie, User-Agent, and\n Accept-Language are the worst offenders, but even the set of headers sent\n can be revealing. To minimize this risk, send only the HTTP headers required\n for DoH: Host, Content-Type (for POST), and if necessary, Accept.\n User-Agent should be included in any development or testing versions.\n- Use EDNS padding options\n\n Follow the guidance in [RFC 8467](https://tools.ietf.org/html/rfc8467) for\n use of EDNS padding options to pad DoH queries to a few common lengths to\n protect against traffic analysis. Use of HTTP/2 padding is also possible but\n unlike EDNS padding, will not elicit padding on responses from DoH servers.\n- Use RFC 8484 POST only for privacy sensitive applications or browser modes\n\n Using POST for DoH queries reduces the cacheability of responses and can\n increase DNS latency, so it is not generally recommended. However, reducing\n caching is probably desirable for privacy sensitive applications, and might\n protect against timing attacks from web apps trying to determine what\n domains the user has visited lately.\n\nIssues\n------\n\nTo report a bug or request a new feature, please open an [issue for DoH](https://issuetracker.google.com/issues/new?component=191657&template=1189745)."]]
