Tratamento de Erros no Flask para APIs resolve um problema recorrente em projetos Python: Transforme exceções esperadas em respostas consistentes e deixe falhas inesperadas observáveis. Este guia mostra o mecanismo, um exemplo executável e os limites que evitam uma implementação frágil.
Conceito e caso de uso
Flask procura handlers pelo código e depois pela hierarquia da exceção, escolhendo o mais específico. O handler precisa devolver o status correto.
Para revisar os fundamentos relacionados, consulte também o guia de APIs Flask. A integração fica mais simples quando cada função recebe dependências e dados explicitamente, em vez de depender de estado global.
Exemplo prático
from flask import Flask, jsonify
from werkzeug.exceptions import HTTPException
app = Flask(__name__)
@app.errorhandler(HTTPException)
def http_error(error):
response = error.get_response()
response.data = jsonify(
code=error.code,
message=error.description,
).get_data()
response.content_type = "application/json"
return responseCrie exceções de domínio específicas, preserve headers de HTTPException e use um formato de erro estável com código e mensagem segura.
Decisões importantes
A escolha correta depende do contrato público, do volume e do comportamento em caso de falha.
Considere como a solução se comporta sob concorrência, entradas vazias e falhas parciais. Documente qualquer limite que afete consumidores e mantenha nomes que expressem a intenção.
Erros comuns
O exemplo mínimo não substitui limites, tratamento de erros e observabilidade. Um handler genérico de Exception pode engolir 404 e 405 ou esconder bugs. Nunca devolva traceback ou mensagem de banco ao cliente.
Evite capturar exceções sem contexto ou retornar resultados parciais como se fossem completos. Uma falha explícita costuma ser mais segura que dados silenciosamente incorretos.
Como validar
Valide o comportamento, não apenas a linha feliz. Teste erro conhecido, rota inexistente, método inválido e exceção inesperada, conferindo status, content-type e logs.