Códigos de erro da API do Twitter e como corrigi-los

#Como ler um erro da API do X

Toda chamada que falha na API oficial do X devolve três coisas: o status HTTP, um corpo JSON e, na maioria dos endpoints, headers de rate limit. O status diz que tipo de falha ocorreu, o corpo diz qual causa dentro desse tipo você encontrou, e os headers dizem quando um rate limit é reiniciado.

Os corpos da API v2 do X seguem um único formato: um title, um detail e um type, que é um URI em https://api.x.com/2/problems/, às vezes acompanhado de um reason como client-not-enrolled. Os endpoints antigos da v1.1, e a resposta de rate limit na documentação da v2 do próprio X, usam em vez disso um array errors com um code numerado e uma message: {"errors": [{"code": 88, "message": "Rate limit exceeded"}]}. Escreva seu código para ramificar por type, reason ou code, porque o X pode reescrever o texto legível a qualquer momento.

Um 200 também pode trazer erros. Quando uma requisição pede vários posts ou usuários e alguns foram apagados ou são protegidos, o X devolve em data os que encontrou e lista o restante em um array errors com o tipo resource-not-found ou not-authorized-for-resource. Verifique a presença de errors em toda resposta, inclusive nas bem-sucedidas.

Imprima o corpo antes de lançar uma exceção. Em Python, raise_for_status() mostra só a linha de status, e a própria equipe do X pede aos desenvolvedores, no fórum, que imprimam response.text, porque o corpo nomeia o parâmetro ou a configuração com problema.

#Status de erro da API do X e como corrigir cada um

A API oficial do X responde com onze status de erro: cinco deles (429, 500, 502, 503 e 504) passam se você esperar e tentar de novo, e os outros seis falham outra vez até você mudar a requisição, as chaves, o saldo ou o acesso. A referência de códigos de resposta (abre em uma nova aba) do X lista dez deles; o 402 é o que ficou de fora.

• 400 Bad Request

  O que significa na API oficial do X

  Um parâmetro está ausente, malformado ou fora do intervalo; o array errors do corpo o nomeia

  Correção

  Corrija o parâmetro que o corpo nomeia

  Repetir?

  Não

• 401 Unauthorized

  O que significa na API oficial do X

  O X não consegue verificar quem chama: chaves erradas ou revogadas, método de autenticação errado, assinatura OAuth 1.0a inválida

  Correção

  Gere as chaves de novo, use a autenticação que o endpoint indica, sincronize o relógio

  Repetir?

  Não

• 402 Payment Required

  O que significa na API oficial do X

  O saldo pré-pago do pagamento por uso acabou: tipo credits-depleted

  Correção

  Adicione créditos ou use as chaves do app com saldo

  Repetir?

  Não

• 403 Forbidden

  O que significa na API oficial do X

  As chaves funcionam, mas este app, token ou conta não pode fazer isso

  Correção

  Leia o reason ou o code: inscrição, permissões, nível de acesso

  Repetir?

  Não

• 404 Not Found

  O que significa na API oficial do X

  O post, o usuário ou a URL não existe, ou o post foi apagado

  Correção

  Confira o ID e o caminho do endpoint

  Repetir?

  Não

• 409 Conflict

  O que significa na API oficial do X

  Um filtered stream está sem regras

  Correção

  Adicione uma regra e depois conecte

  Repetir?

  Não

• 429 Too Many Requests

  O que significa na API oficial do X

  Uma janela de rate limit se esgotou (código 88) ou o teto mensal de uso foi atingido (usage-capped)

  Correção

  Espere o x-rate-limit-reset; um teto de uso espera o próximo ciclo de cobrança

  Repetir?

  No reset

• 500 Internal Server Error

  O que significa na API oficial do X

  Uma falha dentro do X (código 131)

  Correção

  Tente de novo com uma pausa crescente

  Repetir?

  Sim

• 502 Bad Gateway

  O que significa na API oficial do X

  Os servidores de entrada do X não receberam resposta do serviço por trás deles

  Correção

  Tente de novo com uma pausa crescente

  Repetir?

  Sim

• 503 Service Unavailable

  O que significa na API oficial do X

  O X está acima da capacidade (código 130)

  Correção

  Tente de novo com uma pausa crescente

  Repetir?

  Sim

• 504 Gateway Timeout

  O que significa na API oficial do X

  Os servidores do X expiraram na requisição

  Correção

  Tente de novo com uma pausa crescente e peça menos por chamada

  Repetir?

  Sim

#402 Payment Required: créditos da API do X esgotados

Um 402 da API oficial do X significa que o saldo pré-pago por trás do seu app não tem mais nada para gastar, então o X recusa toda chamada cobrada até chegarem novos créditos. O modelo de pagamento por uso do X cobra cada leitura antecipadamente, US$ 0,005 por post e US$ 0,010 por usuário na tabela de preços do X (abre em uma nova aba), e os novos desenvolvedores não têm outra porta de entrada desde 6 de fevereiro de 2026.

Este é o corpo, como um desenvolvedor o publicou no fórum do X em outubro de 2026:

{
  "title": "Payment Required",
  "detail": "credits depleted",
  "type": "https://api.x.com/2/problems/credits-depleted"
}

O link do type não leva a lugar útil: a referência de erros do X não tem entrada para o 402, uma lacuna que um desenvolvedor relatou no fórum do X (abre em uma nova aba) em julho de 2026. As causas, da mais comum para a menos comum:

• O saldo está em zero ou um pouco abaixo. Uma requisição pode deixar um pequeno resto negativo, e o X bloqueia as chamadas até que novos créditos o cubram. Compre créditos no Developer Console; a recarga automática não roda enquanto o saldo está zerado ou negativo.
• O limite de gasto do ciclo foi usado. Um limite que você define no console é o máximo que sua conta gasta em um ciclo de cobrança. Aumente-o ou espere o próximo ciclo.
• As chaves pertencem a outro app. Se o Client ID, o secret ou o Bearer token vêm de um app de outro Project ou de uma conta de desenvolvedor mais antiga, toda chamada cobrada falha mesmo com o console mostrando saldo. O 402 com saldo de US$ 20 (abre em uma nova aba) de um desenvolvedor terminou exatamente aí, em outubro de 2026. Copie as chaves do app com saldo e autorize de novo. Um GET /2/users/me que funciona só prova que a autenticação passa.
• Rajadas esgotam o saldo mais rápido do que a recarga automática o repõe. A página de preços do X avisa que um uso capaz de esvaziar uma recarga em 5 minutos ainda pode ficar sem créditos. Aumente o valor da recarga.

Bom saber

Um 402 e um 429 do tipo usage-capped interrompem leituras pagas, por motivos diferentes. O 402 é dinheiro: adicione créditos e a próxima chamada funciona. O teto de uso é volume: o pagamento por uso para em 3 milhões de leituras de posts por ciclo de cobrança, e depois disso só o próximo ciclo ou um contrato Enterprise, a partir de cerca de US$ 42 mil por mês, devolve as leituras.

#403 Forbidden, 453 e outros erros de acesso

Um 403 significa que o X aceitou suas chaves e recusou a ação, e o reason ou o code numerado no corpo diz qual porta está fechada; repetir a chamada nunca a abre. Os seis que você mais encontra:

• client-not-enrolled (tipo client-forbidden): as chaves vêm de um app que não está vinculado a um Project ou não está inscrito no acesso que o endpoint exige. No Developer Console, coloque o app dentro de um Project de pagamento por uso e use as chaves desse app, como a equipe do X aconselhou em um tópico de outubro de 2026 (abre em uma nova aba).
• 453: "You currently have access to a subset of X API v2 endpoints and limited v1.1 endpoints (e.g. media post, oauth) only." (você tem acesso apenas a um subconjunto de endpoints da v2 e a poucos da v1.1). A chamada foi para um endpoint da v1.1 que não é de upload de mídia nem de OAuth, que é o que tweepy.API e outros clientes mais antigos fazem. Chame o endpoint da v2: tweepy.Client em Python, o pacote twitter-api-v2 em Node.js.
• 261, "Your App cannot perform write actions" (seu app não pode executar ações de escrita): o app está configurado como somente leitura. Mude para Read and Write e gere os tokens de acesso de novo, porque os tokens antigos mantêm a permissão com que foram criados.
• Contas protegidas ou suspensas: código 179 ou o tipo not-authorized-for-resource para um post protegido, 63 para um usuário suspenso. Nada do seu lado os abre; pule o item.
• 326, temporarily locked (temporariamente bloqueada): a conta por trás do token acionou as verificações de spam do X. Entre no x.com e conclua a verificação que o X mostrar.
• 226 e 187 em escritas: o filtro de spam do X ou um post duplicado. A mensagem 226 tem correções próprias no nosso guia sobre por que o X diz que uma requisição parece automatizada.

Curtidas, seguir e quote posts também saíram do acesso self-service em 20 de abril de 2026, então essas escritas agora terminam em um 403 em um app de pagamento por uso. Cada texto 403, com os passos do console para cada um, está no nosso guia sobre o erro 403 Forbidden na API do X.

#429 e 5xx: os erros que se corrigem esperando

Um 429 ou um 5xx é o único tipo de erro da API do X que uma nova tentativa pode corrigir, e só no momento certo: a hora do reset para um 429, uma pausa crescente para um 5xx.

Um 429 com código 88 significa que a janela de um endpoint ficou sem requisições. Três headers em toda resposta mostram onde você está: x-rate-limit-limit, x-rate-limit-remaining e x-rate-limit-reset, um horário Unix em segundos; a maioria das janelas dura 15 minutos. Um 429 do tipo usage-capped é o teto mensal de 3 milhões de leituras de posts, e o header de reset não o levanta. Quanto dura cada limite, no app do X e na API, está no nosso guia sobre o rate limit exceeded no Twitter.

Um 5xx é uma falha do lado do X: 500 e código 131 são erros internos, 503 e código 130 indicam capacidade excedida, 502 e 504 são timeouts entre servidores do X. Espere 1, 2, 4 e 8 segundos entre as tentativas, depois pare e registre o corpo.

Este handler repete só o que pode dar certo e para em todo o resto, com o corpo na mensagem:

import time
import requests

RETRY = {500, 502, 503, 504}

def call_x(url, headers, params=None, tries=5):
    for attempt in range(tries):
        r = requests.get(url, headers=headers, params=params, timeout=30)
        if r.ok:
            body = r.json()
            for err in body.get("errors", []):  # partial errors in a 200
                print("skipped:", err.get("detail"))
            return body
        if r.status_code == 429 and "usage-capped" not in r.text:
            reset = int(r.headers.get("x-rate-limit-reset", time.time() + 60))
            time.sleep(max(reset - time.time(), 1) + 1)
        elif r.status_code in RETRY:
            time.sleep(2 ** attempt)
        else:  # 400-409 and a capped 429: fix the cause first
            raise RuntimeError(f"X API {r.status_code}: {r.text}")
    raise RuntimeError(f"X API still failing after {tries} tries")

#Códigos de erro da API do X por número

Os códigos numerados vêm da API v1.1 e ainda chegam hoje: em respostas da v1.1, em tracebacks do Tweepy e em alguns corpos da v2, como o código 88 em uma chamada com rate limit. As mensagens e os status abaixo são do próprio X, da última tabela de códigos que ele publicou (arquivada em maio de 2023 (abre em uma nova aba)); o 453 vem de relatos de desenvolvedores no fórum do X. Um código que não está aqui volta ao seu status na tabela acima.

• 32

  Mensagem do X

  Could not authenticate you.

  Status

  401

  Causa e correção

  Chaves, token ou assinatura OAuth erradas: gere de novo e assine outra vez

• 34

  Mensagem do X

  Sorry, that page does not exist.

  Status

  404

  Causa e correção

  URL do endpoint ou ID errado

• 50

  Mensagem do X

  User not found.

  Status

  404

  Causa e correção

  A conta foi apagada ou renomeada: busque pelo ID do usuário

• 63

  Mensagem do X

  User has been suspended.

  Status

  403

  Causa e correção

  A conta consultada está suspensa: pule-a

• 64

  Mensagem do X

  Your account is suspended and is not permitted to access this feature.

  Status

  403

  Causa e correção

  A conta do próprio token está suspensa: apele ao X

• 87

  Mensagem do X

  Client is not permitted to perform this action.

  Status

  403

  Causa e correção

  O endpoint não está aberto para este app

• 88

  Mensagem do X

  Rate limit exceeded.

  Status

  429

  Causa e correção

  Espere o x-rate-limit-reset

• 89

  Mensagem do X

  Invalid or expired token.

  Status

  401 ou 403

  Causa e correção

  Token revogado ou expirado: autorize de novo e guarde o novo token

• 92

  Mensagem do X

  SSL is required.

  Status

  403

  Causa e correção

  Chame por HTTPS com TLS 1.2

• 99

  Mensagem do X

  Unable to verify your credentials.

  Status

  403

  Causa e correção

  Consumer secret ou token secret errado

• 130

  Mensagem do X

  Over capacity.

  Status

  503

  Causa e correção

  Tente de novo com uma pausa crescente

• 131

  Mensagem do X

  Internal error.

  Status

  500

  Causa e correção

  Tente de novo com uma pausa crescente

• 135

  Mensagem do X

  Could not authenticate you.

  Status

  401

  Causa e correção

  O desvio do relógio quebrou o timestamp do OAuth: sincronize o relógio

• 144

  Mensagem do X

  No status found with that ID.

  Status

  404

  Causa e correção

  O post foi apagado ou o ID está errado

• 179

  Mensagem do X

  Sorry, you are not authorized to see this status.

  Status

  403

  Causa e correção

  O autor protege seus posts

• 185

  Mensagem do X

  User is over daily status update limit.

  Status

  403

  Causa e correção

  O limite de posts da conta foi usado: espere algumas horas

• 186

  Mensagem do X

  Tweet needs to be a bit shorter.

  Status

  403

  Causa e correção

  O texto passa do limite de tamanho

• 187

  Mensagem do X

  Status is a duplicate.

  Status

  403

  Causa e correção

  O mesmo texto já foi postado: mude-o

• 215

  Mensagem do X

  Bad authentication data.

  Status

  400

  Causa e correção

  Sem header Authorization ou com um header malformado

• 220

  Mensagem do X

  Your credentials do not allow access to this resource.

  Status

  403

  Causa e correção

  O token é restrito: use um com o escopo necessário

• 226

  Mensagem do X

  This request looks like it might be automated.

  Status

  403

  Causa e correção

  O filtro de spam do X barrou uma escrita: reduza o ritmo

• 261

  Mensagem do X

  Your App cannot perform write actions.

  Status

  403

  Causa e correção

  App somente leitura: defina Read and Write e gere os tokens de novo

• 326

  Mensagem do X

  ...this account is temporarily locked.

  Status

  403

  Causa e correção

  Entre no x.com e remova o bloqueio

• 327

  Mensagem do X

  You have already retweeted this Tweet.

  Status

  403

  Causa e correção

  Já feito: trate como sucesso

• 349

  Mensagem do X

  You cannot send messages to this user.

  Status

  403

  Causa e correção

  O destinatário não aceita suas mensagens

• 415

  Mensagem do X

  Callback URL not approved for this client App.

  Status

  403

  Causa e correção

  Adicione a URL de callback exata nas configurações do app

• 453

  Mensagem do X

  You currently have access to a subset of X API v2 endpoints...

  Status

  403

  Causa e correção

  Uma chamada da v1.1 ou um nível de acesso ausente: chame o endpoint da v2

#Tipos de problema da API v2 do X

Nas respostas da v2, o campo type traz a causa: um dos onze tipos que o X documenta, mais credits-depleted, que ele não documenta. Todos os URIs começam com https://api.x.com/2/problems/.

• invalid-request

  O que significa

  Um 400: um parâmetro está errado, listado em errors

  Correção

  Corrija esse parâmetro

• resource-not-found

  O que significa

  O post ou o usuário não existe, muitas vezes dentro de um 200

  Correção

  Pule-o ou confira o ID

• not-authorized-for-resource

  O que significa

  Conteúdo protegido ou privado

  Correção

  Pule-o

• client-forbidden

  O que significa

  Um 403 com um reason, normalmente client-not-enrolled

  Correção

  Mova o app para um Project

• credits-depleted

  O que significa

  Um 402: o saldo pré-pago acabou

  Correção

  Adicione créditos

• usage-capped

  O que significa

  Um 429: o teto mensal de uso

  Correção

  Espere o próximo ciclo de cobrança

• rate-limit-exceeded

  O que significa

  Um 429: uma janela de rate limit

  Correção

  Espere o x-rate-limit-reset

• streaming-connection

  O que significa

  Um problema na conexão do stream

  Correção

  Reconecte com uma pausa crescente

• rule-cap, invalid-rules, duplicate-rules

  O que significa

  Regras do filtered stream: demais, sintaxe inválida, já existentes

  Correção

  Apague, corrija ou pule a regra

• about:blank

  O que significa

  Um erro genérico

  Correção

  Leia o status

O array errors de um 400 nomeia o valor exato que o X rejeitou. Neste caso de outubro de 2026 do fórum do X, a busca full-archive recusou um end_time definido para o instante da requisição:

{
  "title": "Invalid Request",
  "detail": "One or more parameters to your request was invalid.",
  "type": "https://api.x.com/2/problems/invalid-request",
  "errors": [
    {
      "message": "Invalid 'end_time':'2026-10-20T08:04Z'. 'end_time' must be a minimum of 10 seconds prior to the request time.",
      "parameters": { "end_time": ["2026-10-20T08:04Z"] }
    }
  ]
}

A correção que a equipe do X deu: defina o end_time pelo menos 10 segundos no passado ou omita-o.

#Leia dados públicos do X com uma chave de API: Sorsa API

Se as suas chamadas com falha só leem dados públicos, a Sorsa API, uma API e scraper do Twitter (X), tira a maior parte desta página das suas costas. Ela precisa de uma chave de API em um header ApiKey e não exige conta de desenvolvedor do X, app, Project nem OAuth, então os erros de assinatura 401, client-not-enrolled, 453 e 402 nunca se aplicam a ela. Sua própria conta do X também nunca entra no processo.

A Sorsa API devolve todo erro em um único formato de corpo, {"message": "..."}, e estes são os status que você verá:

• 400

  Na Sorsa API

  Um parâmetro está ausente ou malformado

  Correção

  Corrija o parâmetro

• 401

  Na Sorsa API

  invalid api key

  Correção

  Copie a chave do painel de novo

• 403

  Na Sorsa API

  missing key in request header, ou as requisições da chave acabaram

  Correção

  Envie o header ApiKey; recarregue ou faça upgrade

• 404

  Na Sorsa API

  O post ou a conta não existe ou é protegido

  Correção

  Confira o ID

• 429

  Na Sorsa API

  Mais de 20 requisições em um segundo

  Correção

  Espere um segundo

• 500

  Na Sorsa API

  Uma falha do nosso lado

  Correção

  Tente de novo após 1 a 2 segundos

Enviamos os erros de chave à API real em 2 de novembro de 2026. Um header escrito Api-Key em vez de ApiKey conta como nenhuma chave, e a chamada devolve 403:

curl "https://api.sorsa.io/v3/info?username=error_codes_demo_acct" \
  -H "Api-Key: YOUR_API_KEY"

{"message": "missing key in request header"}

Com o header certo e uma chave errada, a mesma chamada devolve 401 e {"message": "invalid api key"}. Requisições com falha nunca são cobradas, e a página de códigos de erro da Sorsa API (abre em uma nova aba) na documentação lista cada status com suas causas.

1. Obtenha uma chave. Cadastre-se e copie sua chave de API do painel. As primeiras 100 requisições são grátis.

2. Leia até 100 posts em uma requisição. O POST /tweet-info-bulk (abre em uma nova aba) recebe links ou IDs de posts e devolve cada post com o perfil completo do autor.

   curl -X POST "https://api.sorsa.io/v3/tweet-info-bulk" \
     -H "ApiKey: YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{"tweet_links": ["2117203385470271488", "2117199027635167232"]}'
   

   {
     "tweets": [
       {
         "id": "2117203385470271488",
         "full_text": "Two layers in every error: status, then cause.",
         "created_at": "2026-11-02T09:12:44Z",
         "lang": "en",
         "likes_count": 41,
         "retweet_count": 6,
         "reply_count": 3,
         "view_count": 5210,
         "user": {
           "id": "1592041833471827968",
           "username": "error_codes_demo_acct",
           "display_name": "Error Codes Demo",
           "followers_count": 1840
         }
       },
       {
         "id": "2117199027635167232",
         "full_text": "Retry 429 and 5xx. Fix everything else first.",
         "created_at": "2026-11-02T08:55:20Z",
         "lang": "en",
         "likes_count": 27,
         "retweet_count": 4,
         "reply_count": 2,
         "view_count": 3380,
         "user": {
           "id": "1592041833471827968",
           "username": "error_codes_demo_acct",
           "display_name": "Error Codes Demo",
           "followers_count": 1840
         }
       }
     ]
   }
   

   Ver resposta completa

3. Busque perfis do mesmo jeito. O GET /info (abre em uma nova aba) devolve um perfil por username, user_id ou user_link, e um 404 significa que a conta não existe mais ou é protegida.

4. Acompanhe o saldo. O GET /key-usage-info (abre em uma nova aba) devolve as requisições restantes e a data em que elas se renovam; a consulta em si é grátis. Tente de novo um 429 após um segundo e trate um 403 com uma chave válida como sinal para recarregar.

Ler posts por ID custa a partir de US$ 0,014 por 1.000 na Sorsa API, 100 posts por requisição, contra US$ 5,00 por 1.000 na API oficial do X, cujo plano de pagamento por uso também para em 3 milhões de leituras de posts por mês:

A partir de 22 de novembro de 2026, a API oficial do X também cobra o perfil do autor que vem com cada post, US$ 0,010 por usuário (aviso do X (abre em uma nova aba)); todo post da Sorsa API traz o perfil completo do autor na mesma requisição. A Sorsa API só lê: para postar, curtir ou enviar mensagens, mantenha a API oficial do X para essas chamadas.

#Corrija o erro que está na sua frente e depois mude suas leituras

Quase todo erro da API do X se resolve de um de dois jeitos: esperar, no caso de um 429 ou de um 5xx, ou mudar a requisição, as chaves, o saldo ou o acesso do app, em qualquer outro caso. Se os seus erros vêm da leitura de posts, perfis ou seguidores públicos, passe essas leituras para a Sorsa API: uma chave de API, mensagens de erro simples, 20 requisições por segundo em todos os planos e posts a partir de US$ 0,014 por 1.000, com 100 requisições grátis para testar hoje.

#Perguntas frequentes