Erros da API

Esta página fornece uma referência para todos os códigos de erro da API Interactions, descreve o formato de resposta de erro e explica como a API gera erros para diferentes tipos de solicitação.

Códigos de erro da API padrão

Esses códigos de erro gerais no nível da solicitação correspondem aos códigos de status HTTP padrão. Use o campo code na lógica do aplicativo para lidar com erros de forma programática.

Código Status do HTTP Descrição Ação recomendada
invalid_request 400 Solicitação inválida O payload da solicitação está incorreto ou contém parâmetros inválidos. Verifique a sintaxe e os parâmetros da solicitação na referência da API.
failed_precondition 400 Solicitação inválida Não é possível processar a solicitação porque um pré-requisito não foi atendido (por exemplo, faturamento desativado). Verifique o status de faturamento do projeto ou os pré-requisitos da conta.
out_of_range 416 Intervalo solicitado não satisfatório O parâmetro de solicitação está fora do intervalo válido. Verifique os valores de parâmetro e limites.
parameter_unknown 400 Solicitação inválida A solicitação contém um parâmetro desconhecido. Remova o parâmetro não reconhecido e tente de novo.
authentication 401 Não autorizado A chave de API está ausente, é inválida ou expirou. Verifique sua chave de API.
payment_required 402 Pagamento necessário Seu saldo de crédito pré-pago foi esgotado. Adicione créditos à sua conta de faturamento ou ative a recarga automática. Não tente novamente: a solicitação não será bem-sucedida até que os créditos sejam adicionados.
permission_denied 403 Proibido Sua chave de API não tem permissão para esse recurso ou o acesso à API do seu projeto está restrito. Verifique as permissões da chave de API, a qualificação do nível do projeto e o status de faturamento. Consulte Resolver problemas de projeto restrito ou indisponível.
not_found 404 Não encontrado O recurso solicitado não foi encontrado. Verifique o caminho e os parâmetros do recurso.
model_not_found 404 Não encontrado O modelo especificado não foi encontrado. Verifique o nome do modelo ou use outro.
already_exists 409 Conflito A entidade que você tentou criar já existe. Verifique se o recurso já existe antes de recriá-lo.
aborted 409 Conflito A operação foi cancelada devido a um conflito ou falha na verificação de simultaneidade. Tente fazer a solicitação novamente em um nível de aplicativo mais alto.
rate_limit_exceeded 429 número excessivo de solicitações Você excedeu o limite de solicitações ou tokens por minuto ou por segundo. Aguarde e tente de novo com uma espera exponencial.
quota_exceeded 429 número excessivo de solicitações Você excedeu sua cota diária. Aguarde até que a cota seja redefinida ou solicite um aumento.
too_many_requests 429 número excessivo de solicitações Você fez muitas solicitações em um curto período. Aguarde e tente de novo com uma espera exponencial.
cancelled 499 Solicitação fechada pelo cliente O cliente cancelou a solicitação antes que ela fosse concluída. Nenhuma ação é necessária. Isso geralmente significa que o cliente foi desconectado.
api_error 500 Internal Server Error (erro interno do servidor) Ocorreu um erro inesperado no servidor. Tente fazer a solicitação novamente. Se o problema persistir, entre em contato com o suporte.
unimplemented 501 Não implementado A operação ou o recurso não foi implementado ou não é compatível. Verifique os recursos da API ou mude para um recurso compatível.
service_unavailable 503 Serviço indisponível O serviço está temporariamente sobrecarregado ou inativo. Aguarde e tente de novo com uma espera exponencial.
deadline_exceeded 504 Gateway Timeout A solicitação não foi concluída dentro do prazo. Remova ou aumente a configuração de prazo do cliente para usar o padrão do servidor.

Códigos de bloqueio de geração

Esses códigos de erro indicam que as restrições de política, segurança ou conteúdo bloquearam a saída do modelo. Quando você receber um desses códigos, modifique sua entrada e tente novamente.

Código Descrição
safety Violações de segurança (conteúdo nocivo) bloquearam a solicitação.
recitation Restrições de direitos autorais ou de recitação bloquearam a solicitação.
language Um idioma sem suporte bloqueou a solicitação.
prohibited_content As diretrizes de conteúdo proibido bloquearam a solicitação.
spii As restrições de informações sensíveis de identificação pessoal bloquearam a solicitação.
blocklist Termos proibidos em uma lista de bloqueio impediram a solicitação.
image_safety Violações de segurança bloquearam a geração de imagens.
image_prohibited_content As diretrizes de conteúdo proibido bloquearam a geração de imagens.
image_recitation Restrições de direitos autorais ou de recitação bloquearam a geração de imagens.
image_other Motivos não especificados bloquearam a geração de imagens.
content_blocked Um motivo de política não especificado bloqueou a solicitação.

Códigos do erro de geração

Esses códigos do erro indicam um problema estrutural com a saída gerada pelo modelo (como uma chamada de função incorreta ou uma chamada de ferramenta não declarada).

Código Descrição
malformed_function_call O modelo produziu uma chamada de função que não pôde ser analisada.
malformed_tool_call O modelo produziu uma chamada de ferramenta que não pôde ser analisada.
unexpected_tool_call O modelo chamou uma ferramenta que não foi declarada na solicitação.
no_image O modelo não conseguiu gerar uma imagem.
too_many_tool_calls O modelo gerou mais chamadas de ferramenta do que o permitido.
missing_thought_signature A resposta não tem uma assinatura de pensamento obrigatória.

Formato da resposta de erro

Todos os erros da API Interactions retornam um objeto error que contém um code e um message. Por exemplo, transmitir um tipo de ferramenta não compatível retorna:

{
  "error": {
    "code": "invalid_request",
    "message": "The value 'invalid_tool_type_xyz' is not supported for 'type' at 'tools[0]'. Supported values: 'function', 'code_execution', 'mcp_server', 'filesystem', 'google_maps', 'google_search', 'bash', 'computer_use', 'file_search', 'url_context'."
  }
}
Campo Tipo Descrição
code string Um código do erro legível por máquina em snake_case.
message string Uma descrição legível por humanos do que deu errado.

Como os erros são enviados

A API gera erros de maneira diferente dependendo se você faz uma solicitação HTTP padrão ou uma solicitação de streaming (SSE).

Solicitações HTTP padrão

Para solicitações padrão (não streaming), a API define o código de status da resposta HTTP (como 400 Bad Request, 401 Unauthorized ou 429 Too Many Requests) e retorna um objeto error no corpo da resposta JSON:

{
  "error": {
    "code": "invalid_request",
    "message": "The value 'invalid_tool_type_xyz' is not supported for 'type' at 'tools[0]'."
  }
}

Solicitações de streaming (SSE)

Para solicitações de streaming (stream: true), a API envia eventos de erro pelo stream de eventos enviados pelo servidor (SSE) com event_type definido como "error". O campo error contém a mesma estrutura code e message:

{
  "event_type": "error",
  "error": {
    "code": "not_found",
    "message": "Failed to get completed interaction: Result not found."
  }
}

Para ver o esquema completo de eventos SSE, consulte a Referência da API Interactions.

A seguir