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çalhoRetry-Aftere 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 deRetry-After. Mais detalhes em Limite de requisições: como funcionam os níveis.insufficient_quotaoucredit_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_exceededouperiod_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 emRetry-Aftere tente de novo, ou use outro modelo.routing_unavailable: o FlowModels está temporariamente desligado, por exemplo por manutenção. Nenhum saldo é reservado. Repita depois deRetry-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.paramindica o campo. Isso inclui um valor alto demais emmax_tokens.unsupported_for_model: o campo é válido, mas o modelo escolhido não o aceita, por exemplotemperatureem um modelo com sampling fixo. Quais campos um modelo entende, você descobre emGET /v1/models.unsupported_field: o campo não é aceito pelo FlowModels de modo geral.input_tokens_exceededoucontext_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çalhoAuthorization: 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.