Recusas e respostas incompletas precisam ser tratadas antes de tentar ler o objeto produzido pela IA. Uma resposta que não entrega os dados esperados não deve virar um registro vazio aprovado. Separe falha de transporte, recusa, interrupção da geração, erro de formato e ausência de informação no documento, pois cada situação exige uma ação diferente.
A proposta é criar um pequeno fluxo de estados ao redor da extração. Ele recebe o resultado do provedor, identifica se houve conclusão utilizável, valida os dados e somente então libera a próxima etapa. Assim, uma automação pode encerrar com uma pendência clara sem transformar a falta de resposta em uma decisão de negócio.
Resumo rápido
- Verifique o estado da resposta antes de acessar campos extraídos.
- Reconheça a recusa pelos sinais documentados da API utilizada.
- Não complete JSON interrompido inventando campos ou fechando estruturas.
- Repita apenas falhas que tenham uma estratégia de recuperação definida.
- Mostre uma pendência compreensível e preserve rastreabilidade sem expor conteúdo sensível.
1. Entenda os resultados que podem chegar
Uma chamada bem-sucedida do ponto de vista da rede não significa que o processo de negócio terminou. O serviço pode devolver uma recusa ou indicar que a geração ficou incompleta. Mesmo uma resposta concluída pode não conter a informação necessária para aprovar um cadastro ou classificar um documento.
Recusa é uma decisão do modelo de não atender à solicitação. Interrupção significa que a geração não terminou como esperado. Falha de formato aparece quando o consumidor não consegue interpretar o contrato esperado. Ausência de informação acontece quando a fonte não permite preencher um campo e a aplicação recebe esse estado de modo previsto.
| Situação | O que observar | Ação proposta |
|---|---|---|
| Erro de transporte | Exceção ou erro da API | Classificar causa antes de repetir |
| Recusa | Sinal específico do provedor | Interromper automação e oferecer revisão adequada |
| Resposta incompleta | Estado e motivo documentados | Avaliar redução de escopo ou nova tentativa limitada |
| Contrato inválido | Falha na interpretação ou validação | Registrar erro técnico e bloquear publicação |
| Dado ausente | Campo nulo previsto no contrato | Solicitar informação ou revisão da fonte |
| Resultado validado | Formato e regras de negócio aprovados | Prosseguir conforme a autorização do fluxo |
Os nomes da tabela são estados internos sugeridos. Não são uma enumeração universal de APIs. Crie um adaptador para cada serviço, responsável por converter seus sinais reais para essa classificação operacional.
2. Leia primeiro o envelope da resposta
Chame de envelope o conjunto de informações que acompanha o conteúdo: estado, identificador da resposta, erro e itens de saída. O consumidor precisa consultar esses dados antes de presumir que existe um objeto extraído pronto para uso.
Na Responses API da OpenAI, a documentação de saídas estruturadas apresenta o tratamento de respostas incompletas e de itens de recusa. Na Chat Completions, o exemplo de recusa usa a propriedade refusal da mensagem. Esses formatos pertencem a interfaces diferentes. Não copie o acesso a campos de uma interface para a outra sem conferir a documentação.
Consulte o guia oficial de saídas estruturadas e a referência de criação de respostas para o contrato efetivamente usado. Mantenha esse detalhe dentro do adaptador, sem espalhar verificações de fornecedor por toda a automação.
Um algoritmo de aplicação pode seguir esta ordem: classificar erros da chamada; conferir estado final; identificar recusa; selecionar o conteúdo esperado; interpretar o objeto; validar estrutura; conferir regras do negócio. Se qualquer etapa falhar, produza uma saída operacional explícita, com motivo e próximo responsável.
O catálogo de integrações OpenAI e ChatGPT ajuda a situar a ferramenta no restante do processo. A interface escolhida precisa continuar registrada na implementação e nos testes, porque o nome comercial do produto não define o formato técnico da resposta.
3. Separe recusa de falta de informação
Um documento sem data de vencimento não implica recusa. A extração pode ter sido concluída corretamente ao informar que esse dado não aparece. Para isso, o contrato precisa representar ausência de maneira legítima, como campo nulo acompanhado de um motivo controlado.
Não instrua o modelo a preencher todos os campos com algum valor para “garantir o JSON”. Essa exigência pressiona o fluxo a aceitar suposições. Declare quais campos admitem ausência e o que o processo fará quando isso ocorrer. Um campo obrigatório na estrutura pode aceitar nulo se o esquema assim definir.
Na especificação JSON Schema, a propriedade existir e seu valor ser nulo são condições diferentes. A documentação de objetos em JSON Schema explica o papel de required. Verifique também o subconjunto de recursos aceito pelo provedor antes de reutilizar um esquema genérico.
Para recusa, interrompa a operação dependente e apresente uma explicação apropriada ao contexto. Evite repetir a mesma solicitação em sequência com instruções para ignorar a recusa. Uma revisão pode verificar se o pedido está mal formulado, se foi enviado material desnecessário ou se a tarefa deve seguir um caminho humano autorizado.
Não transforme o texto da recusa em um motivo livre que será publicado automaticamente. Guarde uma categoria operacional e, quando necessário, uma mensagem revisada para o usuário. O detalhe integral pode conter informações que não pertencem a um painel compartilhado.
4. Planeje recuperação sem criar um ciclo infinito
Uma resposta interrompida pode ocorrer quando o orçamento de saída é insuficiente para a tarefa. Nesse caso, avalie reduzir o escopo, dividir documentos em unidades menores ou ajustar a configuração conforme os limites documentados. A decisão precisa considerar a estrutura esperada: um contrato muito extenso pode gerar trabalho desnecessário.
Não aproveite um prefixo de JSON como se fosse o documento completo. Uma lista interrompida pode omitir itens mesmo que alguém consiga acrescentar colchetes para torná-la sintaticamente válida. A recuperação deve gerar uma nova unidade verificável, com indicação de qual tentativa produziu o resultado aceito.
Falhas de autenticação, entrada inválida, limite de requisições e problemas do serviço merecem políticas diferentes. Use a documentação de erros da OpenAI para identificar a classe, sem tratar qualquer exceção como motivo para repetir imediatamente.
Defina um teto de tentativas por tarefa, um intervalo quando a causa justificar e uma saída final de pendência. Registre a relação entre a tarefa original e suas tentativas. O operador deve poder entender se a aplicação tentou novamente por interrupção, indisponibilidade ou correção de configuração.
Separe geração e efeito externo. Se a IA apenas prepara um cadastro, uma nova tentativa não pode cadastrar o cliente duas vezes. A ação definitiva precisa de uma chave estável e de verificação própria. O artigo sobre webhooks e idempotência na OpenAI detalha essa proteção para eventos.
5. Exemplo: triagem documental em Curitiba
Considere um escritório de administração de imóveis em Curitiba que recebe documentos de interessados. Este exemplo é ilustrativo. A IA organiza informações para um funcionário conferir; ela não decide a aprovação de contratos.
Na primeira tarefa, o arquivo está legível, mas não contém comprovante de endereço. A resposta estruturada informa a ausência prevista no contrato. A tela mostra “comprovante de endereço não localizado” e permite solicitar o documento. Não há motivo para tentar extrair novamente o mesmo conteúdo.
Na segunda tarefa, a resposta termina antes de completar a lista de documentos. O adaptador classifica o resultado como incompleto, sem liberar os itens parciais como conjunto final. O fluxo prepara uma nova tentativa com uma unidade documental menor, desde que a política e a autorização permitam.
Na terceira, o serviço retorna recusa. A aplicação mantém a tarefa pendente e oferece revisão por uma pessoa responsável. O operador recebe a categoria e a identificação da tarefa, sem precisar examinar logs técnicos. A operação não produz uma avaliação negativa do interessado por causa dessa recusa.
Na quarta, a estrutura chega completa, mas um campo identifica o arquivo errado. A validação semântica bloqueia o resultado ao comparar a referência da fonte. Essa falha pertence à qualidade da extração, não à rede nem à segurança do provedor.
O painel agrupa pendências por motivo e responsável. Isso permite corrigir entradas e configuração sem confundir todo problema com “IA fora do ar”. Para relacionar conteúdo e evidência, veja como registrar versões dos documentos citados nas respostas.
6. Teste estados e monitore o efeito no processo
Crie casos controlados para cada saída possível do adaptador. Use respostas sintéticas no teste técnico para reproduzir recusa, interrupção, erro de rede, objeto inválido e campo ausente. Não dependa de provocar uma recusa real toda vez que testar a tela de pendências.
Verifique sobretudo as transições. Um teste deve demonstrar que nenhuma recusa chega à função que aprova o registro; outro deve mostrar que uma resposta incompleta não fecha a tarefa como concluída. Confira ainda que uma recuperação bem-sucedida substitui o estado pendente sem apagar a tentativa anterior.
Para quem acompanha o processo, use indicadores por classe de resultado. Uma taxa agregada de sucesso pode esconder tarefas que terminaram com campos vazios. Registre contagens por conclusão validada, ausência de dados, revisão humana, interrupção e falha técnica. Defina o significado de cada indicador antes de compará-los entre versões.
Nos logs, priorize identificadores, duração, versão do esquema, categoria da falha e decisão tomada. Evite copiar documentos pessoais inteiros para a mensagem de erro. Caso o conteúdo bruto seja necessário à investigação, use armazenamento com acesso e retenção definidos para essa finalidade.
O tutorial de avaliação de aderência a JSON Schema complementa os testes de estrutura. Adicione a ele os estados do fluxo e as regras do negócio: passar no esquema é uma condição necessária em muitos contratos, mas não basta para confiar na conclusão.
Erros comuns
Usar objeto vazio como resposta padrão. Retornar {} após qualquer exceção faz o restante do sistema perder a causa. Prefira um resultado interno com estado explícito, mantendo os dados extraídos indisponíveis até a validação.
Fechar JSON cortado automaticamente. Acrescentar aspas ou colchetes pode esconder campos e itens que nunca chegaram. A sintaxe reparada não comprova completude nem fidelidade à fonte.
Repetir recusa como erro transitório. A recusa exige interpretação do fluxo e eventual revisão, não uma fila infinita de chamadas idênticas. Tenha um caminho de encerramento compreensível para o operador.
Exibir termos técnicos ao cliente. Mensagens como “parse failed” não orientam a próxima ação. Mostre o que falta e o que a pessoa pode fazer, mantendo identificadores técnicos disponíveis para suporte.
Perguntas frequentes
Saída estruturada elimina recusas?
Não. O contrato de formato não obriga o modelo a atender qualquer solicitação. O consumidor deve reconhecer a recusa e tratar a ausência de conteúdo estruturado utilizável antes de acessar os campos do resultado.
Posso usar os campos que chegaram antes da interrupção?
Somente se o seu processo tiver um contrato específico para unidades parciais verificáveis e independentes. Em uma extração que espera um objeto completo, mantenha o resultado interrompido fora da aprovação automática.
Uma nova tentativa deve usar a mesma identificação?
Mantenha uma identificação estável para a tarefa e identificações próprias para cada tentativa. Isso permite acompanhar a recuperação e impedir que a operação de negócio seja executada duas vezes por respostas concorrentes.
Quem deve receber a pendência?
Depende da causa. Configuração inválida vai para a equipe técnica; documento ausente vai para quem pode obtê-lo; dúvida de interpretação vai para um revisor autorizado. Uma fila única sem responsáveis tende a acumular tarefas sem resolução.
