Erros e recuperação

Para erros HTTP em geral e exceções do SDK, consulte o guia de códigos de erro.

Como investigar um erro

Em caso de erro de requisição, verifique a resposta HTTP. Para falhas durante um turno ou na preparação do ambiente, verifique os eventos e o estado salvo.

Para erros estruturados, use error.code na lógica do aplicativo e error.message para explicar a falha. Em erros de validação da requisição, error.param pode indicar qual campo corrigir. O código de tratamento de erros deve funcionar mesmo quando o código de erro for desconhecido ou param estiver ausente.

Na API beta (OpenAI-Beta: agents=v1), o campo error da sessão contém uma mensagem de texto ou null. Consulte o evento SSE error correspondente para obter o código da falha da sessão.

Erros de requisição à API

Esses erros se referem à requisição enviada à API de Agentes. São distintos dos erros de turno, que a API retorna após o início do trabalho.

Limites de taxa da API de Arquivos

Requisições para criar sessões ou anexar arquivos podem retornar HTTP 429 com files_api_rate_limit_exceeded. A API de Agentes usa a API de Arquivos para verificar os arquivos. Essas verificações consomem a cota do usuário autenticado na API de Arquivos. Cada arquivo anexado pode exigir uma verificação separada.

12345678{
  "error": {
    "type": "rate_limit_error",
    "code": "files_api_rate_limit_exceeded",
    "message": "The Files API rate limit for your user has been exceeded. Reduce the rate of requests that access files, then try again.",
    "param": null
  }
}

Reduza o número de requisições simultâneas que acessam arquivos. Limite o número de tentativas e aumente exponencialmente o intervalo entre elas. Novas tentativas imediatas podem continuar esgotando a cota.

Essa resposta HTTP indica que a operação falhou. O caso é diferente de uma sessão ou de um turno que falha de forma assíncrona após uma resposta de criação bem-sucedida. Para identificar essa condição, verifique error.code em vez de comparar o texto da mensagem.

Erros de turno

Um turno que falhou tem status: "failed" e um objeto error com os campos code e message. Por exemplo, se o modelo estiver sobrecarregado, o erro poderá ser:

1234{
  "code": "server_overloaded",
  "message": "The model is temporarily overloaded. Please retry your request after a brief delay."
}

Os códigos de erro de turno não têm um status HTTP próprio. Por exemplo, em caso de sobrecarga, um turno que falhou usa server_overloaded, enquanto uma resposta HTTP pode usar server_is_overloaded.

Erros de sessão e de ambiente

Uma falha no turno nem sempre indica que a sessão falhou. Recupere a sessão para verificar se é possível continuar nela. Se o valor de status for requires_action, execute as ações necessárias. Se a sessão tiver falhado, corrija a causa e crie uma nova sessão com as entradas de que ainda precisa.

Recuperação

Como tentar novamente após falhas temporárias

Use este procedimento quando um limite de taxa for excedido, houver sobrecarga, o tempo de espera se esgotar ou o serviço falhar temporariamente. Em caso de problemas com a entrada, as credenciais ou os limites de cobrança, corrija a causa antes de tentar novamente.

1. Verifique o resultado. Se uma sessão tiver sido criada, recupere a sessão, o turno e os itens salvos. Se o turno ainda estiver ativo, continue acompanhando a execução. Se já tiver sido concluído, use o resultado.
2. Verifique as ações concluídas. Um turno que falhou pode já ter alterado arquivos ou chamado ferramentas externas. Confirme os efeitos dessas ações antes de pedir ao agente que repita o trabalho.
3. Aguarde e limite o número de tentativas. Siga as orientações para novas tentativas. Respeite o intervalo indicado por Retry-After nas respostas HTTP e defina um número máximo de tentativas ou um prazo.
4. Repita a requisição ou inicie um novo turno. Em caso de erro HTTP, verifique o resultado da operação original antes de repeti-la. Se o turno tiver falhado, aguarde até que a sessão esteja no estado idle e envie outra mensagem pedindo ao agente que retome apenas o trabalho pendente. Isso inicia um novo turno na conversa existente.

Examine os resultados das ferramentas mesmo quando o turno for concluído. Interrompa as tentativas automáticas se o erro mudar ou se o número de tentativas atingir o limite.

Como corrigir entradas inválidas

Antes de reenviar a requisição, corrija o campo indicado por error.param ou error.message.

Em caso de erros de tamanho, reduza o tamanho da entrada e do schema de saída ou do resultado da ferramenta antes de tentar novamente. Se a configuração do agente for grande demais, crie uma nova sessão com instruções e definições de ferramentas mais curtas.

Para consultar os requisitos de upload e ver exemplos, veja como resolver erros de upload. Se a mensagem indicar um problema com uma imagem, verifique os dados ou a URL da imagem.

Fluxos desconectados

Um evento error ou a desconexão do fluxo não confirma o estado final do turno. Siga as etapas para recuperar um fluxo desconectado e restabelecer a conexão. Verifique o trabalho salvo antes de reenviar a entrada. Se a sessão recuperada tiver status: "failed" ou se você receber agent.session.failed, interrompa as tentativas de reconexão e siga as orientações para recuperar a sessão.

Em caso de erros persistentes, inclua os IDs da requisição, da sessão e do turno ao entrar em contato com o suporte.