> ## 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.

# Status codes e erros HTTP da API Ghosting

> Referência completa dos status HTTP e códigos de erro da API Ghosting. Entenda o que cada resposta significa e como tratar falhas em integrações.

A API Ghosting usa status HTTP padrão para indicar o resultado de cada requisição. Além do código de status, toda resposta de erro inclui um objeto `error` com código legível por máquina, mensagem descritiva e o status HTTP repetido. Use esta referência para implementar tratamento de erros robusto em clientes, bots e integrações.

## Status HTTP

| Status                      | Significado               | Quando ocorre                                                                       |
| --------------------------- | ------------------------- | ----------------------------------------------------------------------------------- |
| `200 OK`                    | Requisição bem-sucedida.  | Perfil localizado, inclusive contas suspensas (veja nota abaixo).                   |
| `400 Bad Request`           | Requisição inválida.      | Nome de usuário ausente, vazio ou com formato inválido. Código: `INVALID_USERNAME`. |
| `404 Not Found`             | Recurso não encontrado.   | Usuário não existe na plataforma. Código: `USER_NOT_FOUND`.                         |
| `500 Internal Server Error` | Erro interno do servidor. | Falha inesperada no servidor. Código: `INTERNAL_SERVER_ERROR`.                      |

## Códigos de erro

<ResponseField name="INVALID_USERNAME" type="string">
  O parâmetro `username` está ausente, vazio ou contém caracteres inválidos. Retornado com `HTTP 400`.
</ResponseField>

<ResponseField name="USER_NOT_FOUND" type="string">
  O usuário solicitado não existe na base de dados. Retornado com `HTTP 404`.
</ResponseField>

<ResponseField name="INTERNAL_SERVER_ERROR" type="string">
  Erro inesperado no servidor. Tente novamente mais tarde. Retornado com `HTTP 500`.
</ResponseField>

## Estrutura padrão de erro

Todas as respostas de erro seguem este formato JSON:

```json theme={null}
{
  "success": false,
  "error": {
    "code": "USER_NOT_FOUND",
    "message": "...",
    "status": 404
  },
  "meta": {
    "timestamp": "2026-09-06T18:00:00.000Z",
    "version": "v1",
    "executionTimeMs": 4
  }
}
```

<Warning>
  Perfis suspensos retornam `HTTP 200 OK`, não `4xx` ou `5xx`. A resposta inclui `data.status: "suspended"` e `data.banInfo.isBanned: true`. Esse comportamento evita quebras em bots de Discord e outras integrações automatizadas que dependem de sucesso HTTP para continuar o fluxo. Consulte [Moderacao](/guias/moderacao) para detalhes sobre tratamento de contas suspensas.
</Warning>

## Dicas de tratamento

<Tip>
  Sempre verifique `success` no corpo da resposta antes de acessar `data`. Perfis ativos e suspensos retornam `success: true`, mas apenas perfis ativos têm `status: "active"`.
</Tip>

<Tip>
  Para nomes de usuário digitados por usuários finais, normalize removendo o caractere `@` antes de enviar à API, já que o parâmetro não o aceita.
</Tip>