Tratamento de Erros

Códigos de Status HTTP

A API utiliza códigos de status HTTP padrão para indicar o sucesso ou falha de uma requisição.

Códigos de Sucesso

Código	Descrição
200	OK - Requisição bem-sucedida
201	Created - Recurso criado com sucesso

Códigos de Erro do Cliente

Código	Descrição
400	Bad Request - Entrada inválida
401	Unauthorized - Token inválido ou ausente
403	Forbidden - Sem permissão para acessar o recurso
404	Not Found - Recurso não encontrado
422	Validation Error - Erro de validação dos dados

Códigos de Erro do Servidor

Código	Descrição
500	Internal Server Error - Erro interno do servidor

Formato de Resposta de Erro

Todas as respostas de erro seguem um formato consistente:

{
  "detail": "Mensagem de erro descrevendo o que deu errado"
}

Exemplos de Erros Comuns

Erro de Validação (422)

Quando os dados enviados não passam na validação:

{
  "detail": [
    {
      "loc": ["body", "email"],
      "msg": "value is not a valid email address",
      "type": "value_error.email"
    }
  ]
}

Recurso Não Encontrado (404)

Quando o recurso solicitado não existe:

{
  "detail": "Farm not found"
}

Não Autorizado (401)

Quando o token de autenticação é inválido ou está ausente:

{
  "detail": "Could not validate credentials"
}

Sem Permissão (403)

Quando o usuário não tem permissão para realizar a ação:

{
  "detail": "You don't have permission to access this resource"
}

Requisição Inválida (400)

Quando a requisição contém dados inválidos:

{
  "detail": "Invalid pond type. Must be 'nursery' or 'fattening'"
}

Dica

Sempre verifique o código de status HTTP e a mensagem de erro para entender o que deu errado e como corrigir.

Tratando Erros na sua Aplicação

Exemplo em JavaScript

async function fetchFarm(farmId) {
  try {
    const response = await fetch(`/api/v1/farms/${farmId}`, {
      headers: {
        'Authorization': `Bearer ${token}`
      }
    });

    if (!response.ok) {
      const error = await response.json();

      switch (response.status) {
        case 401:
          // Redirecionar para login
          redirectToLogin();
          break;
        case 403:
          // Mostrar mensagem de sem permissão
          showError('Você não tem permissão para acessar este recurso');
          break;
        case 404:
          // Mostrar mensagem de não encontrado
          showError('Fazenda não encontrada');
          break;
        default:
          showError(error.detail || 'Ocorreu um erro inesperado');
      }
      return null;
    }

    return await response.json();
  } catch (error) {
    showError('Erro de conexão');
    return null;
  }
}

Exemplo em Python

import requests

def fetch_farm(farm_id: str, token: str):
    try:
        response = requests.get(
            f"http://localhost:8000/api/v1/farms/{farm_id}",
            headers={"Authorization": f"Bearer {token}"}
        )
        response.raise_for_status()
        return response.json()
    except requests.exceptions.HTTPError as e:
        if response.status_code == 401:
            print("Token inválido ou expirado")
        elif response.status_code == 404:
            print("Fazenda não encontrada")
        else:
            print(f"Erro: {response.json().get('detail')}")
        return None