Resposta rápida
Se o POST /ai/run do Cloudflare AI Gateway retorna HTTP 401 com o código 2009, trate primeiro como credencial inválida ou rejeitada pelo provedor de IA. Pare o retry automático, identifique qual chave chegou ao provedor e valide ou rotacione essa credencial. Repetir a mesma chamada não corrige uma chave expirada, revogada, mal copiada ou enviada ao provedor errado.
A exceção é o Unified Billing: quando o provedor rejeita a credencial administrada pela Cloudflare, a resposta documentada é HTTP 503. Nesse caso, não há uma chave sua para trocar na requisição. Preserve o request ID e o horário, consulte os logs e o Cloudflare Status e encaminhe a evidência ao suporte se a falha continuar.
O que mudou em 6 de outubro de 2026
A Cloudflare padronizou a resposta do endpoint POST /ai/run quando um provedor rejeita credenciais. ElevenLabs deixou de retornar um UserCredentialsError específico com 403, Google Vertex deixou de responder 500 nesse caso e os demais provedores deixaram de expor 402 ou outros códigos próprios. A resposta normalizada agora é 401 com o código 2009.
Para Google Vertex, a Cloudflare também informou que o AI Gateway falha sem repetir a chamada ao provedor. A mudança reduz falsos diagnósticos de indisponibilidade e permite que clientes classifiquem a falha como ação sobre credencial, não como erro transitório de servidor.
Confirme quem devolveu o 401
Um status 401 isolado não basta. O Cloudflare Access, o próprio AI Gateway, o provedor de IA e a sua origem podem devolver esse código por razões diferentes. No fluxo afetado pela mudança, procure o código 2009 no corpo da resposta e confira o registro correspondente nos logs do AI Gateway.
Registre timestamp, provedor, modelo, endpoint, gateway e identificador da requisição. Não copie Authorization, cf-aig-authorization, segredo BYOK ou corpo com dados sensíveis para tickets. Se a aplicação chama outra rota que não POST /ai/run, confirme a documentação daquela rota antes de aplicar esta interpretação.
- Capture o código HTTP e o corpo sanitizado sem imprimir headers de autenticação.
- Localize a mesma chamada nos logs do AI Gateway pelo horário e request ID.
- Confirme que o erro contém código 2009 e identifica rejeição da credencial do provedor.
- Teste a página de status do provedor e da Cloudflare antes de alterar várias integrações ao mesmo tempo.
Descubra qual credencial o AI Gateway usou
A ordem oficial de credenciais evita a maior parte dos diagnósticos errados. Se a requisição envia autenticação do provedor, como um header Authorization, o AI Gateway encaminha esse valor sem consultar BYOK ou Unified Billing. Sem uma chave na requisição, ele procura a chave BYOK salva com alias default. Se nenhuma das duas existir, a rota compatível pode cair no Unified Billing.
Isso significa que um placeholder como Bearer changeme ou uma variável vazia serializada no header pode substituir uma chave BYOK válida e provocar o 401. Para usar a chave armazenada, remova o header do provedor. Preserve o cf-aig-authorization quando o gateway autenticado exigir o token da Cloudflare, pois ele tem outra função.
- Verifique se o cliente envia Authorization, x-api-key ou outro header exigido pelo provedor.
- Se pretende usar BYOK, remova a credencial do provedor da chamada em vez de enviar um valor fictício.
- No painel do AI Gateway, confirme provedor, status da chave e alias selecionado.
- Repita uma única chamada de teste com um prompt sem dados sensíveis.
Como corrigir BYOK e aliases
No painel da Cloudflare, abra AI > AI Gateway > Provider Keys e confirme se a chave aparece como ativa, inválida ou expirada. Para rotacionar, gere uma nova chave no provedor, substitua o valor armazenado e salve. A documentação informa que aplicações passam a usar o novo valor sem mudança no código quando dependem da chave armazenada.
Aliases exigem atenção. Em endpoints de passagem direta ao provedor, o header cf-aig-byok-alias seleciona uma chave diferente de default. Em rotas de Unified Billing, como env.AI.run() e /ai/v1/chat/completions, apenas a chave salva com alias default impede a queda para Unified Billing. Uma chave production ou testing não é consultada nesse caminho.
- Valide a nova chave diretamente no provedor por um teste mínimo e autorizado.
- Atualize a Provider Key correta no gateway e mantenha o alias esperado pela rota.
- Remova headers de provedor do cliente quando a intenção for usar a chave armazenada.
- Teste primeiro em desenvolvimento e só depois promova a rotação para produção.
- Revogue a chave antiga depois de confirmar os consumidores, sem publicá-la em logs ou histórico do shell.
Quando 503 significa Unified Billing
A padronização preserva uma diferença importante: se a chamada usa Unified Billing e o provedor rejeita a credencial administrada pela Cloudflare, o AI Gateway retorna 503. Rotacionar uma chave BYOK não resolve esse cenário se nenhuma chave própria participa da requisição.
Confirme a precedência real antes de abrir um incidente. Se há Authorization na chamada, essa credencial continua sendo a primeira escolha. Se não há header, mas existe uma chave default salva, BYOK vem antes do Unified Billing. Somente quando as duas opções não se aplicam a chamada usa as credenciais e créditos administrados pela Cloudflare.
- Confirme que a requisição não envia uma chave do provedor e não encontra BYOK default.
- Verifique saldo, configuração do gateway, logs e Cloudflare Status.
- Guarde request ID, horário UTC, modelo e provedor para o suporte.
- Use backoff limitado para 503 e interrompa o retry se a janela definida for excedida.
Ajuste retries e alertas
Atualize o cliente para classificar 401 com código 2009 como falha não transitória. A ação esperada é alertar o responsável pela credencial, bloquear novas tentativas com a mesma chave e retomar somente depois de uma correção validada. Isso evita filas de agentes repetindo uma chamada que não pode funcionar.
Mantenha uma política diferente para 429, timeouts e 5xx. Esses erros podem admitir backoff, limite de tentativas e fallback de provedor. Não aplique fallback automático que envia conteúdo sensível para outro provedor sem autorização, e não confunda um 503 do Unified Billing com a regra de 401 para uma chave que você controla.
Use logs sem armazenar segredos ou prompts
Os logs do AI Gateway podem registrar provedor, status, duração, custo e, conforme a configuração, prompt e resposta. Para manter metadados de diagnóstico sem persistir o conteúdo bruto, a Cloudflare documenta o header cf-aig-collect-log-payload: false. Se cf-aig-collect-log for false, nem os metadados são gravados.
Nunca registre headers de autenticação. Em produção, teste a política de logs com dados fictícios, limite quem pode consultar os registros e defina retenção compatível com privacidade e conformidade. Um log útil para este incidente precisa mostrar quando, onde e com qual provedor a falha ocorreu, não o valor da chave.
Limitações e próxima ação útil
Este guia foi verificado em 7 de outubro de 2026. A mudança oficial cobre rejeição de credenciais no POST /ai/run. Outros endpoints, SDKs, gateways intermediários e provedores podem usar corpos ou códigos diferentes. Um 401 sem código 2009 ainda exige correlação com headers, logs e componente que gerou a resposta.
Atualize hoje o tratamento de erros para separar 401/2009 de 503, revise a precedência de credenciais e execute três testes controlados: chave enviada válida, chave enviada inválida e BYOK sem header de provedor. Depois confirme nos logs que cada resultado foi classificado sem expor credenciais e conecte o alerta ao responsável pela rotação.
Faça o próximo teste
Fontes consultadas
Os links abaixo servem para conferir conceitos, orientações oficiais e o critério editorial usado neste conteúdo.
- Standardize provider credential error responses in AI GatewayCloudflare Changelog
- BYOK (Store Keys)Cloudflare Docs
- AI Gateway troubleshootingCloudflare Docs
- AI Gateway loggingCloudflare Docs
- Unified BillingCloudflare Docs
- Cloudflare StatusCloudflare