Skip to main content
Quando uma requisição falha, a Sorsa retorna um código HTTP e um corpo JSON com message descrevendo o problema.

Formato de erro

O campo message contém uma descrição legível. Consulte-o primeiro ao investigar uma falha.

Referência rápida

400 Bad Request

A requisição contém parâmetros inválidos ou ausentes. Causas comuns: ausência de link, id, username ou query obrigatório; tipo ou formato incorreto; corpo JSON vazio ou malformado em POST. Solução: confira os campos na referência da API. Em POST, use Content-Type: application/json e um corpo JSON válido.

401 Unauthorized

A API não conseguiu autenticar sua conta. Causas comuns: cabeçalho ApiKey ausente ou incorreto; chave inválida, excluída ou copiada com espaços. Nomes de cabeçalhos não diferenciam maiúsculas de minúsculas, mas Api-Key e api_key são nomes diferentes. Solução: envie ApiKey: your_key_here e confirme que a chave está ativa no painel. Se necessário, copie-a novamente. Veja autenticação.

403 Forbidden

A chave é válida, mas a requisição foi rejeitada. A cota pode ter acabado ou a assinatura expirado. Solução: consulte GET /key-usage-info ou o painel. Recarregue o saldo ou altere o plano em Billing.

404 Not Found

O recurso não existe ou não está acessível. Causas comuns: nome de usuário alterado, conta excluída ou suspensa, publicação excluída, conta ou publicação protegida, ou URL incorreta. A Sorsa acessa apenas dados públicos. Solução: confirme que o recurso ainda existe e é público no X. IDs de usuários permanecem estáveis após mudanças de nome. Com um ID salvo, consulte /id-to-username/{user_id} ou use user_id diretamente nos endpoints compatíveis.

429 Too Many Requests

O limite de 20 requisições por segundo foi excedido, normalmente por loops sem espera ou workers paralelos com a mesma chave. Solução: uma pausa de 50 ms controla um worker sequencial; chaves compartilhadas exigem coordenação. Outra opção é repetir após uma pausa de um segundo. Veja limites de requisições.

500 Internal Server Error

Houve uma falha interna.
  • Tente novamente após 1 a 2 segundos; falhas transitórias costumam desaparecer.
  • Se persistir ou afetar vários endpoints, consulte a página de status.
  • Procure [email protected] ou o Discord, informando URL, corpo da requisição e horário aproximado. Remova chaves e cabeçalhos de autorização dos diagnósticos.

Tratamento de erros no código

Estes padrões reutilizáveis evitam que uma resposta inesperada interrompa a integração sem tratamento. Python
JavaScript
Os exemplos repetem timeouts, falhas de conexão, 429 e 5xx, com no máximo três tentativas por padrão. Outros erros HTTP falham imediatamente. Respostas de sucesso com JSON inválido também geram erro para investigação. Use Node.js 18+ e instale requests no Python.

Próximos passos