Erros

Entenda as respostas de erro do Webway, os códigos de status e o comportamento seguro de novas tentativas.

Os erros usam um pequeno envelope JSON que SDKs compatíveis com a OpenAI conseguem interpretar:

json

{
  "error": {
    "message": "insufficient credit",
    "type": "insufficient_quota",
    "code": "insufficient_quota"
  }
}

type é o valor geral usado pelas bibliotecas de cliente para decidir como agir. code é mais preciso e só difere de type quando a falha ocorre no provedor.

O envelope acompanha o endpoint. /v1/messages retorna o formato da Anthropic, para que os SDKs da Anthropic e o Claude Code consigam interpretá-lo e aplicar sua própria lógica de novas tentativas sem tratamento especial para este gateway:

json

{
  "type": "error",
  "error": {
    "type": "overloaded_error",
    "message": "the provider is over capacity, retry shortly (request 4f2ab910)",
    "code": "overloaded"
  }
}

Códigos de status

Status	Significado	Tentar novamente?
`400`	JSON, campos ou parâmetros inválidos	Não; corrija a solicitação
`401`	Chave ausente, inválida, expirada ou revogada	Não; substitua a chave
`402`	Seu saldo não é suficiente para cobrir a solicitação	Após adicionar créditos
`403`	O modelo exige sua própria chave do provedor	Não; adicione uma no painel
`404`	Modelo ou endpoint não encontrado	Não; verifique o ID e o caminho
`413`	O corpo da solicitação é grande demais	Não; reduza o conteúdo enviado
`429`	Limite de requisições atingido	Sim; aguarde e tente novamente
`502` / `503`	O provedor está indisponível	Sim; use backoff
`504`	O tempo limite do provedor expirou	Sim; use backoff

402 sempre se refere exclusivamente ao seu saldo. Um problema de cobrança entre o Webway e um provedor é um 502, pois você não pode tomar nenhuma medida a respeito.

Falhas do provedor

Quando a falha vem de um provedor, e não da sua solicitação, code indica qual foi:

`code`	Status	Significado	Tentar novamente?
`model_unavailable`	`502`	O provedor não disponibilizará este modelo. Cabe a nós corrigir	Não
`context_length_exceeded`	`400`	A solicitação é maior que a janela de contexto do modelo	Não
`content_filtered`	`400`	A camada de segurança do provedor recusou o conteúdo	Não
`invalid_request`	`400`	O provedor rejeitou a solicitação	Não
`rate_limited`	`429`	Limite de requisições atingido no provedor	Sim
`overloaded`	`503`	O provedor está acima da capacidade	Sim
`timeout`	`504`	O provedor não respondeu a tempo	Sim
`transport_error`	`502`	A conexão com o provedor falhou	Sim
`upstream_error`	`502`	Sem classificação. Sempre investigado	Talvez

O texto de erro do provedor nunca é repassado. Os serviços upstream descrevem falhas com seu próprio vocabulário, às vezes em outro idioma, muitas vezes mencionando uma infraestrutura que não pertence a você, e esse texto muda sem aviso. Cada falha é classificada em uma das categorias acima e reescrita, para que a mensagem recebida seja estável o bastante para servir como referência nos logs.

Cada mensagem termina com um ID de solicitação do Webway. Informe-o nas solicitações de suporte: ele é o identificador que realmente pode ser consultado.

Erros durante o streaming

Uma solicitação pode falhar depois que os cabeçalhos da resposta já foram enviados. Nesse momento, não há mais como alterar o código de status, então a falha chega como um evento no stream, no mesmo protocolo usado pelo restante — event: error em /v1/messages, um evento error em /v1/responses, um bloco error em /v1/chat/completions. Os valores de code são os mesmos da tabela.

Trate um stream que termina sem seu evento final como uma falha, não como uma resposta curta.

Regras para novas tentativas

Tente novamente apenas em respostas 429 e 5xx transitórias. Use backoff exponencial com jitter, limite o número de tentativas e respeite Retry-After quando estiver presente.

Não tente novamente, sem alterações, em caso de 400, 401, 402, 403, 404 ou 413. A mesma solicitação falhará outra vez.

Não há cobrança por solicitações rejeitadas antes que o provedor comece a processá-las. Uma solicitação que falha após o início da geração pode gerar cobrança pelos tokens já produzidos, inclusive se você a cancelar no meio do streaming.