> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tela.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Erros e retentativas

> Os códigos de status e o corpo de erro da Completion API, e quais chamadas são seguras de repetir

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

| Código | Significado | Causa típica |
| - | - | - |
| `200` | Sucesso. O corpo é a completion, o stream ou a execução. | |
| `400` | O corpo ou a query é inválido. | JSON malformado, um campo com o tipo errado, um parâmetro de query malformado em um endpoint de listagem. Para tarefas, uma variável obrigatória ausente ou um arquivo de tipo não permitido (`INVALID_SCHEMA`). |
| `401` | A chave de API está ausente ou é inválida. | Header `Authorization` errado, chave revogada. |
| `402` | O Workspace atingiu o seu limite mensal de uso. | Documentado para a criação de tarefas com `POST /task`. |
| `403` | A chave não pode acessar o recurso. | Listar execuções com uma chave cujo papel é inferior a `member`. |
| `404` | O recurso não existe ou não está acessível. | `canvas_id` ou `version_id` desconhecido; um `environment_name` que não existe ou não tem versão publicada; um arquivo enviado que não foi encontrado. |
| `5xx` | Uma falha do lado do Tela. | |

Veja [Erros](https://docs.tela.com/api-reference/introduction.md#errors) 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.

```json theme={null}
{
    "code": "NOT_FOUND",
    "message": "Task not found",
    "status": 404,
    "name": "Error"
}
```

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.

> [!NOTE]
>
> 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](https://docs.tela.com/pt/completion-api/async-and-webhooks.md#listando-execucoes-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.

> [!NOTE]
>
> 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](https://docs.tela.com/pt/supported-file-formats.md) 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](https://docs.tela.com/api-reference/introduction.md#compatibility-date).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.