Guia de integração GloopAPI
Tratamento de erros
Trate erros e limites de novas tentativas.
Determine se a solicitação foi aceita antes de decidir tentar novamente. As páginas dos endpoints mostram status HTTP reais, estruturas de erro e exemplos representativos. Protocolos diferentes não compartilham necessariamente a mesma estrutura JSON; respostas binárias de sucesso também podem retornar JSON em caso de falha.
Decisões pela resposta
| Sinal | Próximo passo |
|---|---|
| 400 / Campo ou modelo incompatível | Corrija a entrada conforme o schema do endpoint e o catálogo atual; não repita sem alterações |
| 401 / 403 | Verifique validade da chave, conta, IP, permissões de modelo ou ferramenta e cota |
| 402 / Cota insuficiente | Adicione orçamento ou reduza o escopo das novas solicitações; recupere o registro original das tarefas existentes |
| 404 | Confira identidade do recurso, rota e opções de ativação; não deduza que um envio desconhecido nunca executou |
| 409 | Distinga conflitos de idempotência, tarefas não prontas, mudanças de cotação e recursos referenciados; trate o erro específico |
| 410 | O recurso original foi excluído ou expirou; preserve evidências de cobrança e idempotência, sem criar outra tarefa automaticamente |
| 429 / 5xx / Timeout de rede | Aplique espera progressiva por limites ou aguarde recuperação do serviço e confira a aceitação; repetir só é seguro com contrato de idempotência |
Solicitações aceitas e desconhecidas
HTTP 202 indica aceitação ou conclusão pendente. Uma ferramenta com HTTP 200 também pode representar tarefa com falha; leia status. Aceitar cancelamento não equivale ao estado terminal cancelado. Uma resposta em streaming HTTP 200 pode conter eventos de erro ou terminar de forma anormal.
Em timeout de criação, unknown ou billing_review, preserve a chave original e consulte pela recuperação assíncrona. Tentar salvar novamente e gerar novamente são operações diferentes. Se a origem do arquivo expirou, uma nova tentativa de salvamento também pode não recuperar o resultado.
Informações de diagnóstico
Registre horário, método, caminho, status HTTP, código de erro, request_id disponível, ID da tarefa e chave da solicitação de negócio. Remova dados sensíveis e nunca registre chaves API ou URLs assinadas. Use os erros retornados pela API e seus registros de uso para diagnosticar.
Tentativas automáticas devem ter limites de quantidade e tempo. Investigue solicitações cobráveis se não puder comprovar que não foram aceitas; não use envios duplicados como recuperação padrão.
Códigos estáveis de erro de ferramentas
| Código | HTTP | Tratamento seguro |
|---|---|---|
| invalid_input | 400 | Confira version e input_schema exatos e corrija a entrada da nova solicitação |
| invalid_cursor | 400 | Não crie cursores; atualize a primeira página para obter outro next_cursor |
| quote_required / budget_required | 400 | Complete a cotação ou o limite de custo da nova chamada conforme os campos de recurso |
| quote_expired / quote_stale / invalid_quote | 409 | Confira e recote apenas chamadas novas confirmadas como não enviadas; cotações inexistentes ou de terceiros retornam invalid_quote sem revelar propriedade |
| budget_exceeded | 409 | Orçamento da nova chamada insuficiente; confira maximum_usd e escolha explicitamente o orçamento |
| idempotency_conflict | 409 | A solicitação mudou com a mesma chave; recupere o corpo completo original, sem reenviar automaticamente com outra chave |
| tool_service_unavailable | 503 | Falha de infraestrutura ou recurso temporariamente indisponível; recupere envios desconhecidos com identidade, chave e solicitação completa originais |
Se o resultado da criação for desconhecido, consulte primeiro o run_id original. Sem run_id, repita com a chave de API, Idempotency-Key e solicitação completa originais, incluindo quote_id e max_cost_usd. Não altere um envio desconhecido porque a cotação expirou ou uma opção foi desativada. Só uma nova operação confirmada como não aceita pode ser recotada ou usar outra chave de solicitação.