Erros e limites de taxa
Formatos de resposta de erro, a tabela completa de códigos de status HTTP, o comportamento dos limites de taxa e uma estratégia de novas tentativas que funciona com o Atlas Cloud.
Formatos de resposta de erro
O Atlas Cloud retorna três formatos de erro diferentes, dependendo da parte da API que você chama. Verifique o formato antes de escrever um parser.
Usado pelos endpoints de protocolo LLM e pelos endpoints de geração de mídia:
{
"code": 401,
"msg": "unauthorized",
"request_id": "…",
"data": null
}Toda resposta traz um cabeçalho X-Request-ID. Registre-o — é a forma mais rápida de o suporte rastrear uma chamada específica.
Códigos de status HTTP
| Status | Significado | O que fazer |
|---|---|---|
400 | Requisição malformada: corpo não analisável, model ausente, tipo de conteúdo errado, cabeçalho de retenção inválido ou um webhook_url inválido | Corrija a requisição. O campo msg indica o problema específico |
401 | Falha de autenticação — chave ausente, desconhecida ou expirada | Verifique a chave. Note que um caminho de URL errado também retorna 401, então confira também o endpoint |
402 | Saldo insuficiente ou uma cota do Coding Plan que acabou | Faça uma recarga |
403 | Conta ou usuário sem permissão — inclui usar uma chave do Coding Plan em um modelo que não a aceita | Verifique o escopo da chave ou entre em contato com o suporte |
404 | Recurso não encontrado. Para modelos, isso também cobre modelos indisponíveis para a sua conta | Confira o ID do modelo no catálogo |
413 | O corpo da requisição excede 50 MB | Envie uma URL em vez de Base64 embutido ou envie o arquivo antes |
429 | Limite de taxa atingido | Aplique backoff e tente de novo — veja abaixo |
451 | Bloqueado na sua região | Não é possível repetir |
500 | Erro interno | Tente novamente uma vez e depois reporte com o ID da requisição |
503 | Temporariamente indisponível | Tente novamente com backoff |
504 | Uma requisição síncrona excedeu a espera máxima | Mude para o fluxo assíncrono e consulte o status |
Um 401 nem sempre significa que sua chave está errada. O gateway autentica antes de rotear, então um erro de digitação no caminho também produz 401 em vez de 404. Se uma chave funciona em outro lugar, verifique a URL primeiro.
Códigos de erro no nível da tarefa
Quando uma tarefa assíncrona falha, data.error_code traz um código numérico da plataforma mais específico do que o status HTTP. Por exemplo, 1039 indica que a entrada foi rejeitada pela moderação de conteúdo.
data.error contém uma descrição legível. Registre os dois, junto com o ID da predição.
Limites de taxa
Os limites de taxa se aplicam por conta e por modelo. Exceder um deles retorna 429.
Os endpoints de LLM e de mídia não retornam X-RateLimit-Limit, X-RateLimit-Remaining nem Retry-After. Você não consegue ler sua cota restante nos cabeçalhos da resposta — implemente backoff no cliente.
Os endpoints de cobrança /public/v1 são a exceção: as respostas 429 deles incluem Retry-After.
Se você precisa de limites maiores para uma carga de produção, fale conosco informando o volume de requisições esperado e a combinação de modelos.
Estratégia de novas tentativas
Repita em 429, 500, 503 e 504, além de falhas de rede. Não repita 400, 401, 402, 403, 404 nem 451 — elas falharão da mesma forma.
Repita requisições de leitura à vontade. Tenha cuidado ao repetir envios de geração: uma requisição que expirou pode ter sido aceita mesmo assim, e uma nova tentativa às cegas pode criar — e cobrar por — uma segunda tarefa. Prefira enviar de forma assíncrona e consultar o status, para que uma resposta perdida nunca signifique uma tarefa perdida.
import time, random, requests
RETRYABLE = {429, 500, 503, 504}
def call_with_retry(url, payload, api_key, max_attempts=4):
for attempt in range(max_attempts):
response = requests.post(
url,
json=payload,
headers={"Authorization": f"Bearer {api_key}"},
timeout=60,
)
if response.status_code not in RETRYABLE:
return response
if attempt == max_attempts - 1:
break
# Backoff exponencial + jitter, para muitos clientes não tentarem ao mesmo tempo
delay = min(2 ** attempt, 30) * (0.5 + random.random() / 2)
time.sleep(delay)
return responseErros em streaming
Quando uma requisição em streaming falha antes de o stream abrir, você recebe um erro HTTP normal. Depois que o stream começou, a conexão permanece aberta e o erro chega como um evento dentro do stream — ou seja, um 200 em uma chamada de streaming não garante uma resposta completa. Trate sempre o encerramento no meio do stream.
Os streams também podem conter linhas de comentário SSE começando com : como sinais de keep-alive. Elas não são dados e devem ser ignoradas — a maioria dos clientes SSE faz isso por você, mas parsers feitos à mão frequentemente não fazem.
Obtendo ajuda
Ao relatar um problema, inclua:
- O cabeçalho
X-Request-IDda resposta que falhou - O ID da predição, no caso de tarefas assíncronas
- O ID exato do modelo e o carimbo de data/hora
Fale conosco pelo Suporte.
Relacionado
Last updated on