Enviando códigos de status HTTP em FastAPI
O envio de códigos de status HTTP é uma tarefa essencial em aplicações web, pois esses códigos fornecem informações sobre o resultado das operações realizadas no servidor.
Códigos de Status HTTP
Os códigos de status HTTP são categorizados em grupos, cada um indicando um tipo específico de resposta:
- 1xx (Informativos): Indicam que a solicitação foi recebida e está sendo processada. Essas respostas não incluem conteúdo.
- 2xx (Sucesso): Indicam que a operação foi bem-sucedida.
- 3xx (Redirecionamentos): Indicam que o cliente deve tomar ações adicionais para concluir a solicitação (ex.: redirecionamentos).
- 4xx (Erros do Cliente): Indicam problemas causados por solicitações inválidas feitas pelo cliente.
- 5xx (Erros do Servidor): Indicam falhas internas do servidor ao processar a solicitação.
No FastAPI, o código de status padrão retornado é 200 (OK), mas você pode configurar qualquer código necessário para sua aplicação.
Configurando Códigos de Status com o Parâmetro status_code
O parâmetro status_code
permite definir o código de status HTTP diretamente em manipuladores de rota. Ele é suportado por métodos como get()
, post()
, put()
, entre outros.
Veja um exemplo:
from fastapi import FastAPI
app = FastAPI()
@app.get("/notfound", status_code=404)
def notfound():
return {"message": "Resource Not Found"}
Nesse exemplo, ao acessar o endpoint /notfound
, o cliente recebe uma resposta com o código 404, indicando que o recurso solicitado não foi encontrado.
Uso de Constantes do Módulo status
Para melhorar a legibilidade e a manutenção do código, o FastAPI fornece o módulo status
, que contém constantes predefinidas representando os códigos de status HTTP. Isso elimina a necessidade de lembrar os números específicos.
Exemplos de constantes:
HTTP_200_OK
(código 200)HTTP_404_NOT_FOUND
(código 404)HTTP_500_INTERNAL_SERVER_ERROR
(código 500)
Exemplo utilizando o módulo status
:
from fastapi import FastAPI, status
app = FastAPI()
@app.get("/notfound", status_code=status.HTTP_404_NOT_FOUND)
def notfound():
return {"message": "Resource Not Found"}
Configurando Códigos de Status de Forma Dinâmica
Em muitos casos, o código de status depende de condições específicas durante o processamento da solicitação. Para isso, você pode utilizar o parâmetro status_code
da classe Response
(ou subclasses como JSONResponse
).
Veja um exemplo:
from fastapi import FastAPI
from fastapi.responses import JSONResponse
app = FastAPI()
@app.get("/users/{id}")
def get_user(id: int):
if id < 1:
return JSONResponse(content={"error": "Invalid ID"}, status_code=400)
return JSONResponse(content={"message": f"User ID {id} found"}, status_code=200)
Nesse exemplo, o código de status é definido com base no valor do parâmetro id
. Se o valor for menor que 1, a resposta terá o código 400 (Bad Request); caso contrário, o código será 200 (OK).
Combinando Abordagens
Em cenários mais complexos, é possível combinar a configuração inicial do código de status com modificações dinâmicas baseadas em lógica condicional:
from fastapi import FastAPI, Response, Path
app = FastAPI()
@app.get("/users/{id}", status_code=200)
def users(response: Response, id: int = Path()):
if id < 1:
response.status_code = 400 # Bad Request
return {"message": "Incorrect Data"}
return {"message": f"Id = {id}"}
Nesse exemplo, o código de status padrão é 200 (OK), mas é alterado para 400 (Bad Request) se o valor de id
for menor que 1.
Documentação oficial: