> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ghosting.fun/llms.txt
> Use this file to discover all available pages before exploring further.

# Arquitetura de moderação: 200 OK para perfis suspensos

> Perfis suspensos na API Ghosting retornam HTTP 200 OK com banInfo detalhado. Entenda o design tolerante a falhas e como tratar suspensões em bots.

A API pública do Ghosting adota uma arquitetura de **100% de consulta**: perfis suspensos pela moderação não retornam `403 Forbidden`. Em vez disso, respondem com `HTTP 200 OK` e trazem o status de suspensão dentro do próprio payload. Este guia explica o motivo desse design e mostra como sua integração deve tratar contas suspensas.

## Como funciona

Quando um perfil está suspenso:

1. A API responde com **`HTTP 200 OK`**.
2. O objeto `data` mantém `status: "suspended"`.
3. O bloco `banInfo` vem preenchido com `isBanned: true`, o `reason` detalhado e o horário `bannedAt`.

<Warning>
  Nunca dependa apenas do status HTTP para decidir se um perfil está ativo. Verifique também `data.status` e `data.banInfo.isBanned` antes de exibir informações do perfil.
</Warning>

## Por que HTTP 200 em vez de 403?

<CardGroup cols={2}>
  <Card title="Evita quebras em bots" icon="shield">
    Bots do Discord e scripts automatizados não disparam `UnhandledPromiseRejection` ou `HTTPError` ao consultar perfis suspensos.
  </Card>

  <Card title="Auditoria transparente" icon="lightbulb">
    Servidores podem verificar suspensões por fraude e informar o motivo de forma elegante no canal, sem tratamento especial de erros.
  </Card>
</CardGroup>

## Exemplo de resposta para perfil suspenso

```json theme={null}
{
  "success": true,
  "data": {
    "username": "usuario_exemplo",
    "displayName": "Usuário Exemplo",
    "avatarUrl": "https://ghosting.fun/api/avatar?u=usuario_exemplo",
    "pageUrl": "https://ghosting.fun/p/usuario_exemplo",
    "views": 180,
    "status": "suspended",
    "banInfo": {
      "isBanned": true,
      "reason": "Violação das Diretrizes da Comunidade Ghosting.",
      "message": "A página @usuario_exemplo foi suspensa pela moderação do Ghosting. Motivo: Violação das Diretrizes da Comunidade Ghosting.",
      "bannedAt": "2026-08-30T14:22:00.000Z"
    }
  },
  "meta": {
    "timestamp": "2026-09-06T18:00:00.000Z",
    "version": "v1",
    "executionTimeMs": 5
  }
}
```

## Tratamento correto no cliente

<CodeGroup>
  ```javascript JavaScript theme={null}
  const res = await fetch(`https://ghosting.fun/api/v1/users/${username}`);
  const body = await res.json();

  if (!body.success) {
    // Erros reais (404, 500, etc.)
    console.error("Erro:", body.error.message);
    return;
  }

  const user = body.data;

  if (user.status === "suspended") {
    console.warn(`Perfil suspenso. Motivo: ${user.banInfo.reason}`);
    return;
  }

  // Perfil ativo, prossiga normalmente
  console.log(`${user.displayName} (@${user.username})`);
  ```

  ```python Python theme={null}
  r = requests.get(f"https://ghosting.fun/api/v1/users/{username}")
  body = r.json()

  if not body["success"]:
      print("Erro:", body["error"]["message"])
      exit()

  user = body["data"]

  if user["status"] == "suspended":
      print(f"Perfil suspenso. Motivo: {user['banInfo']['reason']}")
      exit()

  print(f"{user['displayName']} (@{user['username']})")
  ```
</CodeGroup>

<Tip>
  Use o campo `banInfo.message`, que já vem formatado, quando quiser exibir a razão da suspensão diretamente para o usuário final.
</Tip>

## Perfis não encontrados

Se o usuário não existir na plataforma, a resposta será `HTTP 404` com `error.code: "USER_NOT_FOUND"`. Isso é diferente de uma suspensão: um perfil suspenso ainda existe, apenas não está acessível publicamente. Veja [Status codes](/api-reference/status-codes) para todos os cenários de erro.

## Próximos passos

<CardGroup cols={2}>
  <Card title="Schema BanInfo" icon="layers" href="/schemas/ban-info">
    Estrutura completa do objeto de moderação.
  </Card>

  <Card title="Bot Discord" icon="chat" href="/guias/bot-discord">
    Implementação prática com tratamento de suspensão.
  </Card>
</CardGroup>