Códigos de resposta e erros

A X API fornece os seguintes códigos de resposta e de erro para ajudar na compreensão e na depuração em tempo real. Use o guia de depuração e o índice de erros abaixo para obter contexto adicional.

Respostas bem-sucedidas são indicadas por um código HTTP da série 200 e um payload em JSON contendo os objetos solicitados, criados, modificados ou excluídos, juntamente com a interpretação do servidor para sua solicitação.

Respostas de erro são retornadas com um código HTTP fora da série 200. Diferentes códigos de erro indicam diferentes causas para um erro. A X API tenta retornar códigos de status HTTP apropriados para cada solicitação.

​

Códigos de status HTTP da X API v2

Code	Text	Description	Troubleshooting tips
200	OK	A solicitação foi bem-sucedida!
400	Bad Request	A solicitação é inválida ou não pode ser atendida. Uma mensagem de erro complementar fornecerá mais detalhes. Solicitações sem autenticação ou com parâmetros de query inválidos são consideradas inválidas e resultarão nessa resposta.	Verifique o formato da sua query JSON. Por exemplo, se sua regra contiver aspas duplas associadas a uma correspondência exata ou a outro operador, pode ser necessário escapá-las usando uma barra invertida para diferenciá-las da estrutura do JSON.
401	Unauthorized	Ocorreu um problema ao autenticar sua solicitação. Isso pode ocorrer por credenciais ausentes ou incorretas. Também pode ser retornado em outras circunstâncias indefinidas.	Verifique se você está usando o método de autenticação correto e se suas credenciais estão corretas.
403	Forbidden	A solicitação foi compreendida, mas foi recusada ou o acesso não é permitido. Uma mensagem de erro explicará o motivo.	Verifique se sua conta de desenvolvedor tem acesso ao endpoint que você está tentando usar. Talvez seja necessário colocar sua App em uma allowlist (por exemplo, Engagement API ou Ads API) ou inscrever-se para obter acesso.
404	Not Found	O URI solicitado é inválido ou o recurso solicitado, como um usuário, não existe.	Verifique se você está usando parâmetros válidos e o URI correto para o endpoint que está utilizando.
409	Connection Exception	Retornado ao tentar se conectar a um stream filtrado que não possui regras.	Verifique se você criou pelo menos uma regra no stream ao qual está se conectando. O stream filtrado retornará apenas Posts que correspondam a uma regra ativa. Se não houver regras, o stream não retornará nenhum Post.
429	Too Many Requests	Retornado quando uma solicitação não pode ser atendida devido ao limite de taxa da App ou ao Post cap ter sido esgotado. Consulte Rate Limiting.	Verifique o número de solicitações por janela de tempo permitido no endpoint que você está usando. Aguarde a redefinição da janela. Espaçe suas solicitações para evitar atingir os limites de requisições ou faça upgrade para o próximo plano de dados disponível.
500	Internal Server Error	Algo está com problema. Geralmente é um erro temporário, por exemplo, em uma situação de alta carga ou quando um endpoint está temporariamente com problemas.	Verifique a página de status da X API ou o fórum da comunidade de desenvolvedores para ver se outras pessoas estão enfrentando problemas semelhantes, ou simplesmente aguarde e tente novamente mais tarde.
501	Unimplemented	A X API não oferece suporte a este endpoint e não pode atender à solicitação.
503	Service Unavailable	Os servidores da X estão ativos, mas sobrecarregados com solicitações. Tente novamente mais tarde.	Verifique a página de status da X API ou o fórum da comunidade de desenvolvedores para ver se outras pessoas estão enfrentando problemas semelhantes, ou simplesmente aguarde e tente novamente mais tarde.

Quando ocorre um erro durante uma solicitação, informações detalhadas sobre o erro são retornadas no corpo da resposta para ajudar a diagnosticar o problema. Um campo type, que é um URI, indica a natureza do problema, enquanto campos adicionais fornecem mais detalhes. Os campos type, title e detail sempre serão retornados nesses corpos (veja a tabela abaixo). Quaisquer campos adicionais, como no exemplo abaixo, variarão conforme o tipo de erro.

{
  "client_id": "101010101",
  "required_enrollment": "Basic padrão",
  "registration_url": "https://developer.twitter.com/en/account",
  "title": "Cliente proibido",
  "detail": "Esta solicitação deve ser feita usando uma conta de desenvolvedor aprovada que esteja inscrita no endpoint solicitado. Saiba mais consultando nossa documentação."
  "reason": "client-not-enrolled",
  "type": "https://api.x.com/2/problems/client-forbidden"
}

​

Erros parciais

Em alguns casos, você pode ver os erros detalhados acima em uma resposta que retornou o código de status 200. Nesses casos, o endpoint é projetado para retornar os dados que conseguir, ao mesmo tempo em que fornece erros detalhados sobre o que não pôde retornar.

Por exemplo, o endpoint de busca de Posts permite que uma App de desenvolvedor do X solicite mais de um id. Se alguns desses Posts estiverem disponíveis, mas um deles tiver sido excluído, os Posts disponíveis serão retornados no campo data da resposta. Um campo adicional errors será retornado no payload, indicando quais Post(s) solicitados não puderam ser retornados. É usado o mesmo formato dos erros de solicitação completos para facilitar o diagnóstico de problemas.

​

Informações sobre erros

Cada tipo de problema indica a natureza do problema encontrado. Uma lista completa dos problemas que você pode encontrar também está disponível em nossa especificação da API.

A X API tenta retornar códigos de status HTTP apropriados para cada solicitação.

Título	Tipo	Descrição
Problema genérico	about:blank	Um problema genérico sem informações adicionais além daquelas fornecidas pelo código de status HTTP.
Problema de solicitação inválida	https://api.X.com/2/problems/invalid-request	Um problema que indica que esta solicitação é inválida. Se sua solicitação incluir um corpo POST, certifique-se de que o conteúdo seja JSON válido e corresponda à especificação OpenAPI.
Problema de recurso não encontrado	https://api.X.com/2/problems/resource-not-found	Um problema que indica que um determinado Post, Usuário, etc. não existe.
Problema de recurso não autorizado	https://api.X.com/2/problems/not-authorized-for-resource	Um problema que indica que você não tem permissão para ver um Post, Usuário, etc. específico.
Problema de cliente proibido	https://api.X.com/2/problems/client-forbidden	Um problema que indica que seu cliente não tem permissão para fazer esta solicitação.
Problema de recurso não permitido	https://api.X.com/2/problems/disallowed-resource	Um problema que indica que o recurso solicitado viola os preceitos desta API.
Problema de autenticação não suportada	https://api.X.com/2/problems/unsupported-authentication	Um problema que indica que a autenticação usada não é suportada.
Problema de limite de uso atingido	https://api.X.com/2/problems/usage-capped	Um problema que indica que um limite de uso foi excedido.
Problema de conexão do stream	https://api.X.com/2/problems/streaming-connection	Um problema que indica que há algo errado com a conexão.
Problema de cliente desconectado	https://api.X.com/2/problems/client-disconnected	Seu cliente foi desconectado.
Problema de desconexão operacional	https://api.X.com/2/problems/operational-disconnect	Você foi desconectado por motivos operacionais.
Problema de limite de regras	https://api.X.com/2/problems/rule-cap	Você excedeu o número máximo de regras.
Problema de comprimento de regra	https://api.X.com/2/problems/rule-length	Você excedeu o número máximo de caracteres permitidos na sua query ou regra com base no seu nível de acesso. Veja níveis de acesso.
Problema de regras inválidas	https://api.X.com/2/problems/invalid-rules	A regra enviada é inválida.
Problema de regras duplicadas	https://api.X.com/2/problems/duplicate-rules	A regra enviada é duplicada.

​

Dicas de solução de problemas

Depuração do seu código

Ao criar um aplicativo, é normal encontrar erros ou problemas inesperados de tempos em tempos. Abaixo estão algumas dicas de como depurar seu código:

Comece dividindo o problema em partes menores para identificar onde está a falha. Por exemplo, se você está integrando um endpoint REST ou de stream, o problema pode estar em qualquer um dos itens a seguir:

• O endpoint requer autenticação adequada.
• O endpoint requer parâmetros e cabeçalhos válidos. Quaisquer regras de filtragem devem ser construídas usando os operadores corretos e a sintaxe apropriada.
• A URI do endpoint deve estar correta e, no caso de endpoints REST, o método HTTP correto deve ser usado.
• Os dados ou o recurso que você está tentando acessar podem não estar acessíveis a você (por exemplo, dados privados estão disponíveis apenas para usuários autenticados).
• Seu pacote de dados atual fornece acesso apenas a determinados endpoints e a limites de requisições específicos. Confira seu portal do desenvolvedor para mais detalhes.
• Seu código usa uma biblioteca de terceiros para integrar o endpoint ao seu código.
• Seu código precisa interpretar corretamente a resposta do endpoint.

Leia a mensagem de erro correspondente. Ela deve indicar bem qual é o problema. Use as tabelas na seção de códigos de erro e resposta para dicas de solução de problemas específicas para cada código de erro.

Para endpoints REST, você pode usar um cliente REST como o Postman ou o Insomnia para validar as etapas (1) a (5) acima (consulte nosso guia “Introdução ao Postman”). Se a solicitação com o cliente REST retornar um código de status 200 (sucesso), você pode presumir que o problema está no seu código ou na biblioteca que você está usando, e não na própria requisição ao endpoint.

Para endpoints de stream, você pode usar cURL (uma ferramenta de linha de comando para enviar ou obter requisições usando a sintaxe de URL) para verificar se o problema está na requisição ao endpoint (etapas (1) a (5) acima) ou no seu próprio código (etapas (6) a (7) acima).

Problemas de autenticação

• Verifique se você está usando o método de autenticação adequado exigido para o endpoint. Isso pode ser identificado na página de referência da API do endpoint.
• Verifique se suas credenciais de autenticação estão corretas. Você pode verificar ou regenerar as chaves e tokens da sua App na seção Apps do seu painel do desenvolvedor (em “Details”).
• Verifique se você autorizou corretamente sua solicitação OAuth 1.0a com oauth_nonce, oauth_signature e oauth_timestamp.
• Se o problema persistir, considere usar uma biblioteca OAuth, um cliente REST como o Postman ou o Insomnia, ou o xurl.

Consulte nosso guia sobre autenticação para obter mais informações sobre todos os itens acima.

Problemas de rate limit e Post cap

Um erro 429 pode ocorrer se você atingir o rate limit de um determinado endpoint ou se atingir o Post cap.

Se o erro específico ‘Too many requests’ for retornado, você atingiu o rate limit do endpoint. Em outras palavras, você excedeu o número máximo de requisições permitido para um endpoint dentro do período de tempo especificado.

Observe que os rate limits são definidos nos níveis por App e por usuário.

• Nível de X App indica o número de requisições permitidas ao usar OAuth 2.0 App-Only, em que os rate limits são determinados globalmente para toda a App. Por exemplo, se um método permite 15 requisições por janela de rate limit, então ele permite que você faça 15 requisições por janela em nome da sua X App. Esse limite é considerado totalmente separado do limite em nível de usuário. Leia mais em nosso guia sobre OAuth 2.0 App-Only.
• Nível de contexto de usuário indica o número de requisições que podem ser feitas por Access Token de usuário ao usar Contexto de Usuário do OAuth 1.0a ou OAuth 2.0 Authorization Code com PKCE. Por exemplo, se um método permite 15 requisições por janela de rate limit, então ele permite 15 requisições por janela e por Access Token de usuário. Leia mais em nosso guia sobre como obter os Access Tokens de um usuário com OAuth 1.0a e OAuth 2.0.

Comece verificando os rate limits do endpoint que você está usando. Você pode encontrar essas informações na página de referência da API do endpoint e no novo painel do portal do desenvolvedor.

Consulte nossa documentação para informações adicionais sobre rate limits, incluindo como usar cabeçalhos HTTP para acompanhar a situação da sua App em relação a um determinado rate limit, como se recuperar de um erro 429 por rate limit e dicas para evitar ser limitado logo de início:

• Rate limits para endpoints v2

Se você recebeu o erro específico “Usage cap exceeded: Monthly product cap”, isso significa que você atingiu o Post cap do seu nível de acesso. Temos diversos detalhes sobre o que são esses Post caps em nossa página de documentação.

Problemas de Post ausente

Siga as etapas abaixo se você esperava que um Post fosse retornado, mas ele não foi entregue pelo endpoint.

• Verifique sua regra para garantir que você está usando os operadores e a sintaxe corretos. Divida a regra em cláusulas menores para garantir que você esteja usando a sintaxe correta.
• Se a conta da qual o Post foi enviado estava protegida no momento em que o Post foi criado, o Post não será retornado — mesmo que a conta seja pública no momento da solicitação ao endpoint. Normalmente você pode verificar isso usando a X Advanced Search: se um Post não for exibido usando a funcionalidade X Advanced Search, você deve presumir que ele não será retornado pelo endpoint.

As etapas a seguir se aplicam apenas a endpoints de stream:

• Você estava conectado ao stream quando o Post foi enviado? Lembre-se de que o timestamp entregue no Objeto Post indica o horário em UTC. Se você sofreu uma desconexão quando o Post foi enviado, reveja os recursos de recuperação e redundância disponíveis para preencher quaisquer dados perdidos.
• Sua regra estava ativa quando o Post foi enviado? Lembre-se de que o timestamp entregue no Objeto Post indica o horário em UTC.

Problemas de desconexão por buffer cheio

Você pode receber um dos seguintes erros quando seu stream não acompanha a velocidade de entrega de dados e sua App não consome os dados do stream rápido o suficiente:

This stream has been disconnected because your client was unable to keep up with us.

This stream has been disconnected for operational reasons.

Permitimos que a entrega fique atrasada por um período e mantemos um buffer temporário de staging para cada stream do nosso lado; mas, se você não conseguir alcançar, iniciamos uma desconexão para que você se reconecte no ponto atual. Observe que isso pode levar à perda de dados (para os dados que estiverem no buffer no momento da desconexão por buffer cheio).

Isso pode ocorrer durante grandes picos de volume de dados. Em geral, recomendamos usar um processo de buffer, separado do processo de processamento, para consumir dados rapidamente.

Se você for um cliente Enterprise usando endpoints v1.1, saiba mais sobre como otimizar sua App para evitar desconexões como esta em nossos artigos sobre connection e sobre como consumir dados de streaming aqui e aqui.

Há uma variedade de ferramentas disponíveis para recuperar Posts perdidos devido a uma desconexão, incluindo as listadas abaixo. Observe que as seguintes ferramentas estão disponíveis apenas com endpoints v1.1 no nível de acesso Enterprise.

• Redundant Connections - Com múltiplas conexões, consuma o stream a partir de vários servidores para evitar perda de dados quando uma delas for desconectada.
• Replay - Recupere dados dos últimos 5 dias usando um stream separado.
• Backfill - Reconecte-se em até 5 minutos e retome de onde parou.
• Historical PowerTrack - Recupere dados de todo o arquivo da X.

​

Obtenha ajuda

O fórum da comunidade do X está disponível para que você faça perguntas técnicas sobre a plataforma de desenvolvedores do X. Este é um fórum de discussão onde você encontrará perguntas de outros desenvolvedores e informações técnicas sobre diversos tópicos relacionados ao uso da X API.

Incentivamos você a participar, respondendo a perguntas e interagindo nas discussões em nosso fórum. Colaboradores do X também estão presentes para oferecer suporte.

Fórum da comunidade do X

​

Antes de publicar uma pergunta

• Pesquise na documentação para desenvolvedores da X por informações relacionadas ao seu problema
• Procure no fórum da comunidade por perguntas semelhantes de outros desenvolvedores
• Leia as diretrizes do fórum da comunidade

​

Ao publicar uma pergunta, certifique-se de incluir as seguintes informações

• Uma descrição do problema
• A chamada à API realizada (inclua os cabeçalhos, se possível)
• A resposta retornada pela X (inclua quaisquer mensagens de erro)
• O que você esperava receber em vez disso
• Lista de etapas realizadas para solucionar o problema
• Lista de etapas necessárias para reproduzir o problema
• Se relevante, o período durante o qual o problema ocorreu
• Se relevante, o App ID, ID do Post, etc.
• Qualquer trecho de código ou captura de tela relevante

Inclua apenas um tópico/pergunta por Post.

Se você tiver solicitações de recursos ou feedback, envie-os por meio do X Developer Platform Feedback Form.

Para questões relacionadas a políticas, como suspensão de App, entre em contato com o Policy support.

Para questões relacionadas à X, como login e suporte à conta, use o X Help Desk.