FlowModels

Entender as mensagens de erro do FlowModels

Publicado em 11. novembro 2026

Quando o FlowModels recusa uma requisição, sua aplicação recebe um status HTTP e uma descrição do erro em JSON. Veja aqui como ler uma mensagem de erro e o que significam os códigos mais comuns.

Como é uma mensagem de erro

Toda resposta de erro tem o mesmo formato, compatível com a OpenAI:

{
  "error": {
    "message": "…",
    "type": "rate_limit_error",
    "code": "rate_limit_exceeded",
    "param": null
  },
  "flowai_request_id": "01HXYZ…"
}

O que importa é o error.code. Em erros de entrada, param indica o campo afetado. O flowai_request_id também aparece no cabeçalho x-request-id. Salve esse valor nos seus logs e informe-o ao abrir um chamado no suporte. O mesmo identificador aparece no registro de requisições.

429: requisições demais ou sem orçamento

Um 429 tem duas causas bem diferentes. Por isso, olhe sempre o código.

  • rate_limit_exceeded: a cota por minuto do seu nível ou o limite próprio da chave se esgotou. Espere a quantidade de segundos indicada no cabeçalho Retry-After e tente de novo.
  • concurrent_requests_exceeded: já há tantas requisições rodando ao mesmo tempo quanto seu nível permite. Envie menos em paralelo e repita depois de Retry-After. Mais detalhes em Limite de requisições: como funcionam os níveis.
  • insufficient_quota ou credit_balance_exhausted: o saldo disponível não é suficiente para essa requisição. Faça uma recarga, veja Recarregar saldo e ativar a recarga automática.
  • spend_limit_exceeded ou period_spend_limit_exceeded: o limite mensal da chave ou o limite de gastos da sua equipe foi atingido. Uma recarga não resolve neste caso. Aumente o limite ou espere o mês virar, veja Configurar o limite de gastos e os alertas.

Não repita automaticamente em loop as requisições com erro de orçamento. Elas vão continuar falhando até você alterar o saldo ou o limite.

503: sem capacidade temporariamente

  • provider_overloaded: o provedor do modelo escolhido está sem capacidade no momento. O problema não é a sua conta. Espere os segundos indicados em Retry-After e tente de novo, ou use outro modelo.
  • routing_unavailable: o FlowModels está temporariamente desligado, por exemplo por manutenção. Nenhum saldo é reservado. Repita depois de Retry-After.
  • pricing_unavailable: no momento não há um preço confiável para o modelo. Tente de novo mais tarde.

Em 502 routing_execution_failed, a requisição não pôde ser concluída, geralmente porque o provedor não respondeu. Aqui também costuma ajudar repetir mais tarde. O FlowModels não troca por conta própria para outro modelo, ele repassa o erro para você.

400: a requisição tem um erro

Um 400 significa que há algo errado na sua requisição. Repetir sem alterar nada não adianta.

  • invalid_field_value: um campo tem um valor inválido ou falta um campo obrigatório. param indica o campo. Isso inclui um valor alto demais em max_tokens.
  • unsupported_for_model: o campo é válido, mas o modelo escolhido não o aceita, por exemplo temperature em um modelo com sampling fixo. Quais campos um modelo entende, você descobre em GET /v1/models.
  • unsupported_field: o campo não é aceito pelo FlowModels de modo geral.
  • input_tokens_exceeded ou context_length_exceeded: a entrada é grande demais para o modelo. Reduza o histórico ou o conteúdo enviado.

401, 403, 404 e 410

  • 401 invalid_api_key: a chave é desconhecida, expirou ou foi bloqueada. Verifique em Chaves de API.
  • 401 invalid_token_source: a chave não foi enviada no cabeçalho Authorization: Bearer.
  • 403 insufficient_key_scope: a chave tem a permissão errada, por exemplo Gerenciar chaves em vez de Usar IA para uma chamada de modelo.
  • 403 account_suspended: o acesso da sua equipe ao FlowModels está bloqueado. Em Faturamento aparece Acesso bloqueado. Fale com o suporte.
  • 404 model_not_found: o identificador do modelo não existe. Verifique em Modelos.
  • 410 model_deprecated: o modelo foi descontinuado e não pode mais ser chamado. Mude para outro modelo.

Bom saber

A lista completa de códigos está na documentação em https://flowmodels.one/pt/docs. Se você repetir requisições POST depois de uma queda de conexão, envie um Idempotency-Key fixo por operação. Assim, uma requisição que já deu certo não é executada nem cobrada uma segunda vez.

Este artigo foi útil?

Voltar para Modelos, limites e erros