El problema de las claves de API que nunca caducan
Una clave emitida hace años, que nunca se ha rotado y que hoy sigue siendo válida, no es una comodidad. Es un riesgo que nadie ha revisado de verdad en años.
Por qué publicamos nuestros códigos de error en lugar de ocultarlos
Una solicitud a la API fallida ya es un mal momento en el día de cualquiera. Empeora cuando el código de error que se devuelve no está explicado en ninguna parte, y quien lo depura tiene que adivinar si un 400 significa un parámetro mal formado, un campo obligatorio que falta o algo totalmente distinto que casualmente comparte el mismo código de estado con otros tres problemas sin relación. Un error sin documentar no es solo una molestia. Convierte un arreglo de cinco minutos en una investigación sin final claro, que a veces acaba en un ticket de soporte que se podría haber evitado leyendo una página que debería haber existido.
Publicamos nuestros códigos de error con claridad en la documentación de errores, donde indicamos lo que significa realmente cada uno y lo que suele provocarlo, junto a las páginas de autenticación y de límites de frecuencia, que describen las otras formas en que puede fallar una solicitud. El objetivo es que, cuando algo sale mal, la respuesta esté a una página de distancia, y no sea una suposición basada en las convenciones generales de los códigos de estado HTTP, que pueden o no corresponderse claramente con lo que hizo nuestro sistema en concreto.
Ocultar los detalles de los errores, incluso sin querer a través de una documentación escasa, a veces nace de un instinto que suena razonable: mostrar exactamente por qué falló una solicitud podría, en teoría, ayudar a alguien que sondea una API en busca de debilidades. En la práctica, esta preocupación rara vez compensa el coste real. La inmensa mayoría de las personas que se encuentran con un código de error son desarrolladores legítimos que intentan arreglar su propia integración, no adversarios que cartografían una superficie de ataque. Diseñar la documentación de errores pensando en el raro actor malicioso, a costa de la claridad para todos los demás, invierte la balanza.
Publicar los códigos de error con claridad también aporta una disciplina de diseño: obliga a la coherencia interna. Si cada código de error tiene que documentarse con una explicación sencilla, resulta mucho más difícil acumular un montón de condiciones de error improvisadas y solapadas que solo entiende del todo el ingeniero que las escribió. Escribir la documentación es también, discretamente, una forma de revisión de código del propio manejo de errores, porque un error difícil de explicar con claridad suele ser señal de que la condición subyacente no se pensó bien desde el principio.
Los fallos relacionados con la cuota reciben un tratamiento parecido mediante cabeceras de respuesta, y no solo con códigos de error. Cada respuesta incluye tu límite de cuota, tu uso, la cuota gratuita restante, el uso de tu red, el crédito restante y la hora de reinicio, así que una solicitud que falla por la cuota no es en absoluto un código de estado misterioso. Es un número que podrías haber comprobado antes de enviar la solicitud, y que puedes leer directamente en la respuesta que falló.
Nada de esto elimina la frustración de una solicitud fallida. Solo significa que la frustración debería terminar en la documentación, con una respuesta real, en lugar de continuar en una cola de soporte o en un juego de adivinanzas entre viejas publicaciones de foros sobre lo que un código de estado de una API totalmente distinta podría haber significado en una situación parecida.