Una respuesta de error no es una nota al pie de una API: forma parte del contrato del que depende cada integración, tanto como una respuesta correcta. Hemos estandarizado el formato de error en todos los endpoints nativos de My Geocode, de modo que un fallo tiene el mismo aspecto sin importar qué parte de la API lo haya producido.
Tanto si una solicitud falla por un parámetro ausente, una clave no válida, una cuota agotada o una coordenada mal formada, la respuesta sigue una estructura única y predecible. Esa coherencia significa que el código de gestión de errores escrito una vez, para un endpoint, funciona igual con todos los demás endpoints nativos sin necesidad de una lógica de gestión distinta para cada uno.
Los fallos relacionados con la cuota merecen una mención especial, ya que son los más habituales en una integración activa. Cuando una solicitud superaría la cuota de una clave o de una red, la respuesta lo deja claro, y las cabeceras de cuota que ya están presentes en cada respuesta, X-Quota-Limit, X-Quota-Used, X-Quota-Free-Remaining y las demás, indican exactamente cuánto margen había antes de la solicitud que falló. Esa combinación permite a un cliente distinguir un problema de cuota de un problema de autenticación o de una solicitud incorrecta solo con la respuesta, sin adivinar.
Los hosts de compatibilidad son una excepción deliberada a esta estandarización, y con razón. Todo su propósito es reproducir exactamente la estructura de solicitud y respuesta de otro proveedor, y eso incluye el aspecto de los errores. Una solicitud con el formato de Bing Maps REST Services que falla sigue recibiendo un error en el propio formato de error de Bing, porque reproducir esa estructura con precisión, tanto en el éxito como en el fallo, es la razón de ser de un host compatible (drop-in). Estandarizar los errores ahí rompería precisamente la compatibilidad que el host existe para ofrecer.
Para todo lo que esté construido sobre nuestros endpoints nativos, este formato más limpio debería hacer que la gestión de errores sea notablemente más sencilla de escribir y mantener. Una única rutina de análisis, un único conjunto de campos esperados y un comportamiento coherente en /v1/forward, /v1/reverse, /v1/ip, /v1/timezone, /v1/elevation, /v1/autocomplete y /v1/postcode por igual.
La documentación completa del formato de error, con los nombres de los campos y las causas habituales, está disponible en /docs/errors/. Si tu integración tiene ahora ramas de gestión de errores separadas para distintos endpoints nativos, es un buen momento para simplificarlas en una sola.