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

# Erros

> Status codes, formato do body de erro e os códigos machine-readable que cada endpoint pode retornar.

Erros seguem um único shape em toda a API:

```json theme={null}
{
  "status": 409,
  "code": "AGENT_NAME_TAKEN",
  "message": "Agent name already exists in this workspace",
  "timestamp": "2026-05-25T14:30:12.234567Z"
}
```

| Campo       | Notas                                                                            |
| ----------- | -------------------------------------------------------------------------------- |
| `status`    | Echo do status HTTP. Sempre bate com o código da resposta.                       |
| `code`      | Identificador estável e machine-readable — seguro para usar em `switch`.         |
| `message`   | Explicação para humanos. A redação pode mudar; não dê match por padrão de texto. |
| `timestamp` | Horário do servidor quando o erro ocorreu. Útil para tickets de suporte.         |

## Referência de status codes

| Status                | Quando você vai ver                                                                                                                         |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| `200` / `201` / `204` | Sucesso. `201` para create, `204` para delete sem body.                                                                                     |
| `400`                 | Validação falhou, JSON malformado, campos desconhecidos, paginação inválida, campo imutável tocado.                                         |
| `401`                 | API key ausente ou inválida. Veja [Autenticação](/pt/api-reference/authentication).                                                         |
| `403`                 | Workspace sem permissão para esta operação (ex.: tentar usar feature fora do plano).                                                        |
| `404`                 | Recurso não encontrado. Ou o ID não existe, ou pertence a outro workspace.                                                                  |
| `408`                 | Mensagem síncrona excedeu o timeout — aumente `timeoutSeconds` (max 300) ou use o endpoint de streaming.                                    |
| `409`                 | Conflito — nome duplicado, recurso já vinculado, transição de estado não permitida.                                                         |
| `422`                 | Violação de regra de negócio — ex.: limite do plano, ciclo detectado, configuração de canal bloqueada.                                      |
| `429`                 | Limite de rate ou cota. Aguarde e tente de novo.                                                                                            |
| `500`                 | Erro de servidor. Não deveria acontecer — abra um bug com o `timestamp` do body.                                                            |
| `502`                 | Serviço upstream inacessível (a request chegou no gateway, mas um downstream — Composio, payment provider — falhou). Geralmente transiente. |

## Códigos de erro comuns

Estes são os códigos que você vai ver mais. O conjunto completo está documentado por endpoint na API Reference.

### Autenticação

* `MISSING_API_KEY`, `INVALID_API_KEY_FORMAT`, `INVALID_API_KEY` — todos `401`.

### Validação

* `VALIDATION_ERROR` — `400`. Body tem campos inválidos, enum errado ou propriedade desconhecida.
* `MALFORMED_JSON` — `400`. Body não é JSON válido.
* `IMMUTABLE_FIELD` — `400`. Tentou mudar um campo que não pode ser editado depois da criação (ex.: `toolType`).

### Estado de recurso

* `AGENT_NOT_FOUND`, `CLIENT_NOT_FOUND`, `KNOWLEDGE_SOURCE_NOT_FOUND`, etc. — `404`.
* `ALREADY_LINKED`, `AGENT_NAME_TAKEN`, `SKILL_NAME_TAKEN`, `EXTERNAL_MCP_NAME_TAKEN` — `409`.

### Regras de negócio

* `NO_DRAFT_VERSION` — `409`. O agente não tem draft pra modificar; publique antes ou crie um novo draft.
* `SUB_AGENT_CYCLE` — `422`. Linkar criaria um ciclo (A → B → A).
* `OAUTH_NOT_SUPPORTED_VIA_API` — `422`. Registro OAuth requer o fluxo web do Studio.
* `CHANNEL_CONFIG_NOT_ALLOWED_VIA_API` — `422`. Config de WhatsApp requer Meta OAuth no Studio web.
* `HTTP_TOOL_LIMIT_REACHED` — `422`. Workspace atingiu o limite do plano.

## Guia de retry

| Status                        | Retry?                                                                    |
| ----------------------------- | ------------------------------------------------------------------------- |
| `400` / `404` / `409` / `422` | **Não.** Corrija a request.                                               |
| `401`                         | **Não.** Corrija a key.                                                   |
| `408`                         | **Às vezes.** Aumente `timeoutSeconds` ou use streaming.                  |
| `429`                         | **Sim**, com backoff exponencial. Comece em 1s, max 30s.                  |
| `500` / `502`                 | **Sim**, com backoff exponencial. Se um `500` persistir, é bug — reporte. |

Operações idempotentes (`GET`, `DELETE`) são sempre seguras para retry. Para `POST` / `PATCH`, faça retry só em falhas transientes (`429`, `502`, erro de rede) para evitar criação dupla.