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

INVALID_USERNAME · string

O parâmetro username está ausente, vazio ou contém caracteres inválidos. Retornado com HTTP 400.

USER_NOT_FOUND · string

O usuário solicitado não existe na base de dados. Retornado com HTTP 404.

INTERNAL_SERVER_ERROR · string

Erro inesperado no servidor. Tente novamente mais tarde. Retornado com HTTP 500.

Estrutura padrão de erro

Todas as respostas de erro seguem este formato JSON:

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

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 para detalhes sobre tratamento de contas suspensas.

Dicas de tratamento

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

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.