Resposta vazia da API LLM? Causas e Soluções
Quando aparece um erro de resposta vazia da API LLM, o servidor geralmente respondeu e a string vazia vem de como a resposta é lida. Aqui está uma lista de verificação, ordenada pela frequência de cada causa.
AtualizadoUnfiltered AI

Pontos principais
- Imprima o JSON bruto primeiro. A maioria das respostas vazias é um problema de análise, não uma falha no serviço.
- Verifique finish_reason: length, stop e tool_calls explicam cada campo de conteúdo em branco.
- Em streams, leia delta.content de forma defensiva e ignore chunks sem choices.
- Um 429 ou um proxy que armazena em buffer SSE pode parecer uma resposta vazia em alguns clientes.
Comece olhando a resposta bruta
Antes de alterar qualquer configuração, capture exatamente o que retornou. Bibliotecas wrapper ocultam a causa: um simples print(response.choices[0].message.content) mostra None ou uma string vazia, seja o corpo vazio, contendo uma chamada de função, atingindo o limite de comprimento ou nunca tendo chegado.
Use curl para evitar interferência do código cliente e inclua cabeçalhos com -i:
curl -i https://api.unfilteredaiapi.com/v1/chat/completions \
-H "Authorization: Bearer YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "uncensored",
"messages": [{"role": "user", "content": "Say hello in five words."}]
}'
Leia três coisas no resultado. Primeiro, a linha de status: 200 significa que uma conclusão foi produzida, 429 significa que um limite foi atingido, um erro de autenticação como 401 geralmente aponta para a chave. Segundo, choices[0].finish_reason. Terceiro, os cabeçalhos da resposta, especialmente X-Request-Id (mantenha-o se entrar em contato com suporte) e X-Balance-USD, que mostra se a conta ainda tem crédito. Se essa chamada curl retornar texto, o serviço está funcionando e o problema está no seu cliente. Se retornar um corpo de erro, você já tem a causa.
Causa 1: a mensagem contém uma chamada de ferramenta, não texto
Se passar tools e o modelo chamar uma função, a mensagem terá tool_calls e content nulo ou vazio. Ler só content mostra resposta vazia. Solução: verifique tool_calls, execute a função, anexe resultado com role: "tool" e chame a API novamente.
from openai import OpenAI
client = OpenAI(base_url="https://api.unfilteredaiapi.com/v1", api_key="YOUR_KEY")
resp = client.chat.completions.create(
model="uncensored",
messages=[{"role": "user", "content": "What is the weather in Oslo?"}],
tools=[{
"type": "function",
"function": {
"name": "get_weather",
"description": "Get current weather for a city",
"parameters": {
"type": "object",
"properties": {"city": {"type": "string"}},
"required": ["city"],
},
},
}],
)
msg = resp.choices[0].message
if msg.tool_calls:
print("tool call:", msg.tool_calls[0].function.name, msg.tool_calls[0].function.arguments)
else:
print(msg.content)
Se não quiser usar ferramentas, remova os campos tools e tool_choice. Uma definição residual de ferramenta é causa comum de texto vazio.
Causa 2: a resposta foi cortada ou nunca começou
finish_reason explica a maioria dos casos restantes.
- length. A conclusão atingiu um limite de tokens. Você pode ter definido
max_tokensmuito baixo, como 1 ou 10. O parâmetro é opcional aqui, pois a conclusão pode usar o que sobrar da janela de 100.000 tokens, então a correção mais simples é removê-lo. Se você precisar de um limite, defina-o com margem. - stop. Modelo concluiu normalmente ou gerou sua string
stop. Sequência como quebra de linha para a resposta na primeira linha, podendo resultar em nada se o modelo começar com linha vazia. Remova ou ajuste a sequência. - tool_calls. Consulte a seção anterior.
Estouro de contexto é outro problema de comprimento. A janela tem 100.000 tokens (prompt + conclusão). Se o histórico quase preenche a janela, não há espaço para resposta. Limite ou resuma conversas antigas. A página sobre memória de conversa e janela de contexto longa mostra como controlar o histórico. O corpo da requisição não pode exceder 8 MB.
Mais uma pequena armadilha: o modo JSON. Com response_format definido como json_object, inclua a palavra JSON nas suas instruções e descreva a forma desejada. Um prompt vago mais o modo JSON produz uma saída fina ou trivial que parece vazia quando você extrai uma chave dela.
Causa 3: streaming lido incorretamente
O streaming via SSE envia muitos chunks pequenos. Nem todo chunk carrega texto. O primeiro chunk geralmente tem apenas o role, o último chunk de conteúdo carrega um finish_reason com um delta vazio, e o chunk final que relata o uso pode chegar com uma lista choices vazia. Código que indexa choices[0] em cada chunk vai falhar, e código que trata um chunk sem texto como a resposta inteira vai imprimir nada.
from openai import OpenAI
client = OpenAI(base_url="https://api.unfilteredaiapi.com/v1", api_key="YOUR_KEY")
stream = client.chat.completions.create(
model="uncensored",
messages=[{"role": "user", "content": "Write two sentences about rain."}],
stream=True,
)
parts = []
for chunk in stream:
if not chunk.choices:
continue
delta = chunk.choices[0].delta
if delta.content:
parts.append(delta.content)
text = "".join(parts)
print(text if text else "[no content received]")
Dois problemas de ambiente parecem streams vazios. Proxy/CDN com buffer segura chunks até o fim, causando delay ou timeout. Desative o buffer no streaming. Stream ocupa slot de concorrência até o fim; streams abandonados (aba fechada, close() faltando) usam seus 8 slots gradualmente, gerando 429. Veja o backend FastAPI com streaming SSE.
Causa 4: um erro que seu cliente engoliu
Alguns wrappers HTTP retornam uma string vazia em status não 200 em vez de lançar uma exceção. Registre o código de status e o corpo para cada falha. Os casos que importam:
| Status ou código | Significado | O que fazer |
|---|---|---|
429, rate_limited | Mais de 300 requisições por minuto com uma chave completa (60 no trial) | Reduza a velocidade, adicione uma fila |
429, concurrency | Mais de 8 requisições simultâneas com uma chave completa (2 no trial) | Limite seus workers |
429 com Retry-After: 5 | Sobrecarga temporária | Espere 5 segundos e tente novamente |
| 401 | Tipicamente uma chave faltando ou errada | Verifique o cabeçalho Authorization: Bearer |
| 404 | Tipicamente um caminho ou base URL errados | A URL base deve terminar em /v1 |
Um wrapper de nova tentativa simples ocupa algumas linhas e remove uma classe inteira de respostas em branco esporádicas:
import time
from openai import OpenAI, RateLimitError
client = OpenAI(base_url="https://api.unfilteredaiapi.com/v1", api_key="YOUR_KEY")
def ask(messages, tries=4):
for attempt in range(tries):
try:
r = client.chat.completions.create(model="uncensored", messages=messages)
return r.choices[0].message.content or ""
except RateLimitError as e:
wait = 5
retry_after = getattr(e.response, "headers", {}).get("retry-after")
if retry_after:
wait = int(retry_after)
time.sleep(wait)
raise RuntimeError("still limited after retries")
Requisições falhas ou recusadas não são cobradas, então retry não custa o dobro. Confirme comparando X-Balance-USD antes e depois de uma chamada falha.
Causa 5: endpoint, modelo ou chave errados
Uma lista de verificação rápida de erros de configuração que produzem resultados estranhos em vez de erros visíveis:
- A URL base é
https://api.unfilteredaiapi.com/v1. A ausência de/v1ou a duplicação dela pode gerar um corpo 404 que um cliente tolerante converte em resposta vazia. - O nome do modelo é
uncensored, grafado exatamente assim. Definir um modelo do catálogo de outro provedor é um erro comum de copiar e colar. - Apenas
POST /v1/chat/completionseGET /v1/modelsexistem. O endpoint de completions legado, embeddings e rotas de imagem não estão disponíveis, então uma biblioteca que os chama recebe uma resposta inútil. - A chave é enviada como um token Bearer e não tem espaços em branco ou aspas estranhos de um arquivo env.
Chame GET /v1/models com sua chave para testar a conectividade. Se ele listar o modelo, a URL base e a chave estão corretas e o problema está no corpo da requisição. O quickstart tem a requisição mínima para comparação, e o FAQ cobre acesso, limites e faturamento.
Registro que encurta o próximo incidente
Respostas vazias são difíceis de depurar após o fato porque ninguém registrou o que o servidor enviou. Algumas linhas de registro transformam um mistério em uma consulta.
- Registre o cabeçalho de resposta
X-Request-Idem todas as chamadas, bem-sucedidas ou não. - Registre
finish_reason, as contagens deusagee o comprimento do texto retornado. - Para streams, registre quantos pedaços chegaram e quantos continham texto. Zero pedaços com texto e um término normal apontam para o seu parser. Zero pedaços no total apontam para a rede ou para o proxy.
- Configure alertas na proporção de respostas em branco em relação ao total de chamadas, não em eventos isolados. Uma resposta em branco em mil é ruído. Cinco por cento é um bug.
Ao comparar uma chamada com falha com uma que funciona, difira os corpos da requisição primeiro. Um prompt do sistema alterado, uma lista stop adicionada, um max_tokens menor ou um nome de modelo trocado explicam a maioria das regressões. Coloque o corpo da requisição no log para uma amostra de chamadas, após remover qualquer dado pessoal.
Se vários usuários relatarem brancos ao mesmo tempo e o seu teste com curl também falhar, a causa provavelmente não é o seu código. Verifique um 429 com Retry-After primeiro, já que a sobrecarga temporária é sinalizada dessa forma, e tente novamente após o atraso indicado. Se o teste com curl funcionar e o seu aplicativo falhar, trabalhe a partir do lado do cliente usando as seções acima.
Se a resposta for curta em vez de vazia
Às vezes, o sintoma é uma resposta de uma linha onde você queria uma página. Isso é um problema de prompt mais do que de transporte. Solicite o comprimento e a forma que deseja ("pelo menos 400 palavras, em três parágrafos"), coloque a instrução na mensagem do sistema e aumente um pouco o temperature se o modelo estiver sendo sucinto. O modelo é ajustado para responder sem recusas de conteúdo para uso adulto lícito, então uma resposta curta raramente é uma recusa; é mais frequentemente uma solicitação pouco especificada. Conteúdo sexual envolvendo menores de idade é o único limite rígido e é sempre recusado.
Ainda travado? Envie ao suporte o X-Request-Id da resposta com falha, o tempo aproximado e o corpo da requisição sem sua chave. Isso permite que alguém localize a chamada exata. Se você é novo no serviço, a página da chave tem o resgate do crédito de teste, que é suficiente para dezenas de chamadas de depuração.
Mais guias
Perguntas e respostas
Por que message.content é null?
Na maioria das vezes, o modelo retornou tool_calls em vez de texto, ou o stream foi lido incorretamente. Verifique finish_reason e tool_calls na mensagem antes de tratá-la como um erro.
Uma resposta vazia custa dinheiro?
Requisições falhas ou recusadas não são cobradas. Se uma chamada foi bem-sucedida e produziu tokens, você verá contagens de uso, e X-Balance-USD nos cabeçalhos mostra o seu saldo.
Uma janela de contexto cheia pode causar saída em branco?
Sim. Prompt e completion compartilham 100,000 tokens, então um histórico quase cheio deixa pouco ou nenhum espaço para a resposta. Diminua ou resuma as rodadas anteriores.
Por que meu stream mostra nada, depois tudo de uma vez?
Um proxy ou CDN provavelmente está armazenando em buffer a resposta SSE. Desative o buffer para essa rota para que os chunks passem conforme chegam.
Sua chave está a um formulário de distância
Crie uma conta, copie a chave e altere a URL base. Essa é toda a configuração.