Pular para o conteúdo principal
A Completion API informa problemas em dois lugares: como um erro HTTP quando a própria requisição é rejeitada, e como uma execução com status: "failed" quando a requisição foi aceita mas o Canvas não conseguiu terminar. Trate os dois casos.

​
Códigos de status HTTP

Veja Erros na introdução da referência da API para as convenções compartilhadas por todos os endpoints.

​
O corpo do erro

Erros são objetos JSON com um code, uma message legível, o status HTTP e name: "Error". Alguns erros acrescentam um campo details com mais informações sobre o que foi rejeitado.
Decida com base em status e code, e não em message, que é feita para pessoas e pode mudar.

​
Execuções com falha

Quando uma execução assíncrona não consegue terminar, a chamada HTTP que a criou ainda assim retornou 200. A falha aparece depois como status: "failed" na execução que você consulta com GET /v2/chat/completions/{id}, no payload enviado para a sua webhook_url e em GET /v1/completion-run. Trate failed como final: uma execução não sai desse status sozinha.
Os campos que uma execução com falha traz sobre a causa não estão documentados aqui. A execução também fica visível no Usage do Canvas, onde você pode inspecionar as suas entradas.

​
O que é seguro repetir

  • GET /v2/chat/completions/{id}, GET /v1/completion-run e GET /v3/files/{id} são só de leitura. Repita-os à vontade, por exemplo após um timeout de rede ou um 5xx.
  • POST /v2/chat/completions inicia uma execução. Cada requisição aceita cria uma nova execução com o seu próprio ID e conta para o seu uso, então repetir às cegas após um timeout pode executar o Canvas duas vezes. Nenhuma chave de idempotência está documentada para este endpoint. Se a requisição foi rejeitada com um 4xx, nenhuma execução foi criada e você pode enviar uma requisição corrigida.
  • POST /v3/files só reserva uma URL de upload e um ID de arquivo. Repeti-lo cria outro ID, o que não causa problema desde que você referencie aquele para o qual realmente enviou o arquivo.
Para se recuperar de um POST /v2/chat/completions incerto (você nunca recebeu a resposta), marque cada requisição com um identificador seu, como order-123, e consulte GET /v1/completion-run?tags=order-123 antes de enviá-la de novo. Se existir uma execução com essa tag, leia o resultado dela em vez de criar outra. Veja Listando execuções anteriores. Quando for repetir após um 5xx ou um erro de rede, espere entre as tentativas e acrescente alguma aleatoriedade ao intervalo, para que muitos clientes falhando ao mesmo tempo não repitam no mesmo instante.
Limites de taxa e de concorrência da Completion API não estão documentados aqui. Se você receber um código de status que indique limitação, reduza o ritmo e repita após um intervalo.

​
Evitando erros antes que aconteçam

  • Envie todas as variáveis que o Canvas marca como obrigatórias, com os nomes mostrados em Conectar via API. As variablesDefinitions do metadata de uma execução em GET /v1/completion-run listam cada variável com o seu type (file, text ou mixed) e se ela é required.
  • Envolva URLs de arquivo em um objeto com file_url, e confira que o arquivo está em um formato suportado e acessível pela internet (ou foi enviado com /v3/files).
  • Use só um entre canvas_id, version_id e application_id, e só combine environment_name com canvas_id.
  • Não envie stream nem async com application_id: tarefas são sempre assíncronas.
  • Mantenha o header x-compatibility-date nos endpoints de arquivo que o exigem. Veja Data de compatibilidade.