Erros e limites de taxa

Os erros voltam como JSON no formato de erro da OpenAI. A mensagem indica o que aconteceu, code é um identificador estável legível por máquina, e um id de requisição é anexado a cada mensagem:

{
  "error": {
    "message": "Model \"gpt-5.5-typo\" is not offered here. Check the model name for typos, or switch to a model from our supported list. (request id: 20260705...)",
    "type": "new_api_error",
    "code": "model_not_found"
  }
}

Sempre inclua o id de requisição ao entrar em contato com o suporte ou abrir um ticket no Discord. Ele nos permite encontrar sua requisição exata nos logs.

Os códigos de status que você realmente vai encontrar:

Duas situações bem diferentes compartilham o status 503. A primeira é congestionamento temporário:

HTTP/1.1 503 Service Unavailable

{
  "error": {
    "message": "All providers for model \"kimi-k2.6:free\" are busy right now (they hit their rate limit). This is not a spelling error. Please try again in a little while, or switch to another model. (request id: 20260705...)",
    "type": "new_api_error",
    "code": "get_channel_failed"
  }
}

O código get_channel_failed (todos os provedores ocupados) significa que todo provedor gratuito daquele modelo está momentaneamente limitado por taxa. Isso se recupera sozinho em minutos: tente novamente ou troque de modelo. O código model_not_found (não oferecido aqui) significa que o próprio nome do modelo não resolve, e tentar novamente nunca vai ajudar. Verifique erros de digitação ou consulte o nome atual no catálogo.

Trate o 503 com get_channel_failed como nova tentativa ou fallback e o 503 com model_not_found como um erro definitivo no seu cliente.

Um 429 pode vir de várias camadas:

• Nosso teto de modelos gratuitos: 1 requisição por minuto por modelo gratuito por usuário. Um teto de justiça para que os pools compartilhados sobrevivam aos horários de pico.
• Limites do provedor upstream: o provedor por trás de um modelo gratuito atingiu o próprio teto ("temporarily rate-limited upstream", ou seja, temporariamente limitado por taxa a montante).
• Orçamentos diários de tokens em alguns pools gratuitos; eles reiniciam à meia-noite UTC.
• Tetos de tokens por minuto que disparam em prompts muito grandes.
• Um limite de concorrência por usuário quando muitas requisições rodam em paralelo.

Modelos pagos não têm limites de taxa impostos pelo UnoRouter.

Quando nosso teto de 1 por minuto dispara, você recebe cabeçalhos padrão de limite de taxa, para que os clientes possam recuar com precisão:

HTTP/1.1 429 Too Many Requests
Retry-After: 38
X-RateLimit-Limit: 1
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1783198478

Retry-After é dinâmico: os segundos que de fato restam na sua janela, não um 60 fixo. A mensagem de erro também nomeia o gêmeo pago do modelo, que não tem limite.

Alguns modelos normalmente pagos são oferecidos gratuitamente com um teto de tamanho de requisição. Prompts grandes demais recebem 413 com uma mensagem como: Request body too large for gpt-4.1 model. Max size: 8000 tokens.

O teto se aplica apenas à rota do teste gratuito; o modelo pago aceita prompts de comprimento total.

Respeite o Retry-After nos 429. Tente novamente o 503 get_channel_failed após uma breve espera, ou recorra a outro modelo. Não tente novamente erros de classe 400, eles são determinísticos.

Requisições que falharam ou foram recusadas não são cobradas: qualquer pré-reserva no seu saldo é reembolsada quando a requisição dá erro.