> ## Documentation Index
> Fetch the complete documentation index at: https://docs.1to1ai.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Erros
> Como a API sinaliza os erros e como tratá-los.
A API segue um contrato **REST puro**: o status code HTTP é o sinal de
sucesso ou erro.
## Formato da resposta
```json Sucesso theme={null}
{ "message_uuid": "...", "wamid": "..." }
```
```json Erro theme={null}
{
"code": "WINDOW_CLOSED",
"message": "The 24-hour messaging window is closed. Send an approved template to reopen it."
}
```
Um sucesso retorna o payload direto, sem envelope. Um erro retorna sempre
`{ code, message }` — ambos os campos são garantidos.
Faça `switch` sobre `code`: é estável e faz parte do contrato. O `message`
é texto humano de ajuda e pode ser refinado entre versões da API sem aviso.
As mensagens são entregues em inglês (padrão de indústria, mesmo padrão que
Stripe, GitHub ou Linear). Se precisar exibi-las traduzidas para o usuário
final, mapeie-as no seu cliente por `code`.
## Famílias de status
| HTTP | Significado | Repetir? |
| ----- | --------------------------------------------------------------------------------- | -------------------------- |
| `2xx` | Sucesso — `200` leitura, `201` criação, `202` aceito (async), `207` multi-status. | — |
| `4xx` | Erro da requisição — auth, validação ou recurso inexistente. | Não, corrija antes. |
| `429` | Rate limit excedido. | Sim, após o `Retry-After`. |
| `5xx` | Erro do servidor. | Sim, com backoff. |
## Catálogo de códigos
O status HTTP de cada código é **típico**: o endpoint específico pode retornar
outro status se o contexto justificar. O authoritative por endpoint vive na
**Referência da API**. A tabela aqui é referência geral, não contrato
vinculante por endpoint.
Os códigos de ambiguidade de resolução de conversa (`PHONE_NUMBER_AMBIGUOUS`,
`USERNAME_AMBIGUOUS`) podem aparecer em **qualquer** endpoint que aceite uma
referência `conversation` por `phone`/`username`, mesmo que sua Referência da
API liste outros códigos `409`.
### Auth e tenant
| Code | HTTP | Descrição |
| ------------------------- | ---- | ------------------------------------------------------------------------------------------------ |
| `INVALID_API_TOKEN` | 401 | O token não existe ou foi revogado. Gere um novo em Settings → API Token. |
| `TOKEN_BUSINESS_MISMATCH` | 403 | O token não pertence ao slug do negócio na URL. Verifique que ambos se refiram ao mesmo negócio. |
### Rate limit
| Code | HTTP | Descrição |
| --------------------- | ---- | -------------------------------------------------------------------------------------------------------------------- |
| `RATE_LIMIT_EXCEEDED` | 429 | Você excedeu o bucket de 60 req/min. Espere os segundos do header `Retry-After`. Ver [Rate limits](/pt/rate-limits). |
### Validação
| Code | HTTP | Descrição |
| ---------------------- | ---- | --------------------------------------------------------------------------------------------------- |
| `INVALID_REQUEST` | 400 | O body não passou na validação de schema (campo faltante, tipo incorreto, valor fora do intervalo). |
| `INVALID_CURSOR` | 400 | O cursor de paginação é inválido ou expirou. Reinicie a listagem sem cursor. |
| `BATCH_LIMIT_EXCEEDED` | 400 | O grupo de ações excede o máximo permitido em uma única requisição. O `message` carrega o cap real. |
### Conversa, contato e canal
| Code | HTTP | Descrição |
| ----------------------------------- | ---- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| `CONVERSATION_NOT_FOUND` | 404 | O identificador de `conversation` (`uuid`, `whatsapp_user_id`, `username` ou `phone`) não resolve para nenhuma conversa do negócio. |
| `CONTACT_NOT_FOUND` | 404 | O identificador de contato não resolve para nenhum do negócio. |
| `PHONE_NUMBER_AMBIGUOUS` | 409 | Vários contatos compartilham esse telefone (números reciclados / identidades separadas). Identifique a conversa por `whatsapp_user_id` ou `uuid`. |
| `USERNAME_AMBIGUOUS` | 409 | Vários contatos compartilham esse username. Identifique a conversa por `whatsapp_user_id` ou `uuid`. |
| `CHANNEL_NOT_CONFIGURED` | 422 | A conversa não tem um canal de WhatsApp configurado. Conecte um no dashboard antes de enviar. |
| `TESTER_CONVERSATION_NOT_WRITABLE` | 422 | Conversas tester não aceitam envios reais ao WhatsApp. Use uma real, ou limite a ação a tags/notas/mailbox. |
| `TRANSCRIPTION_REQUIRED_TO_RESOLVE` | 422 | `POST /conversation/resolve`: a conversa tem mídia recebida com transcrição pendente. Complete a transcrição manual pelo dashboard e tente novamente. |
### Tags
| Code | HTTP | Descrição |
| --------------------------- | ---- | ---------------------------------------------------------------------------------------------------------------------------- |
| `TAG_NOT_FOUND` | 404 | A tag não existe para este negócio. |
| `TAG_ALREADY_ASSIGNED` | 409 | A tag já está atribuída a esta conversa. |
| `TAG_NOT_ASSIGNED` | 404 | A tag não está atribuída, então não pode ser removida. |
| `TAG_AMBIGUOUS` | 409 | Há várias tags com esse nome. Use `tag_uuid` para desambiguar. |
| `TAG_BUSINESS_MISMATCH` | 400 | A tag pertence a outro negócio. |
| `CANNOT_ASSIGN_DEFAULT_TAG` | 422 | A tag é gerenciada pelo sistema (administrada pelo backend, ex.: a de conversão pendente) e não pode ser atribuída pela API. |
| `CANNOT_REMOVE_DEFAULT_TAG` | 422 | A tag é gerenciada pelo sistema (administrada pelo backend, ex.: a de conversão pendente) e não pode ser removida pela API. |
### Mailboxes e categorias
| Code | HTTP | Descrição |
| ---------------------------- | ---- | -------------------------------------------------------------------------------- |
| `CATEGORY_NOT_FOUND` | 404 | A categoria de mailbox não existe para este negócio. |
| `CATEGORY_BUSINESS_MISMATCH` | 403 | A categoria pertence a outro negócio. |
| `AMBIGUOUS_CATEGORY` | 409 | Há várias categorias com esse nome. Use `category_uuid` para desambiguar. |
| `MAILBOX_NOT_FOUND` | 404 | O mailbox não existe para este negócio. |
| `MAILBOX_ALREADY_ASSIGNED` | 409 | A conversa já está nesse mailbox. |
| `AMBIGUOUS_MAILBOX` | 409 | Há vários mailboxes com esse nome. Use `mailbox_uuid` para desambiguar. |
| `NO_MAILBOXES_IN_CATEGORY` | 422 | A categoria não tem mailboxes configurados. Adicione pelo menos um no dashboard. |
### Guards de pré-condição
| Code | HTTP | Descrição |
| ------------------------- | ---- | -------------------------------------------------------------------------------------------------------------- |
| `WINDOW_CLOSED` | 422 | A janela de 24h está fechada. Envie um [template](/pt/templates) aprovado para reabri-la. |
| `WALLET_BLOCKED` | 402 | A wallet de tokens do modelo de AI requerido está vazia ou bloqueada. Recarregue para continuar. |
| `VISION_WALLET_BLOCKED` | 402 | A wallet de vision tokens está vazia. O processamento de visão requer recarga. |
| `VISION_BLOCKED` | 402 | O pipeline de visão da thread está bloqueado. Resolva a mídia pendente no dashboard antes de tentar novamente. |
| `NO_AI_EMPLOYEE_ASSIGNED` | 422 | A conversa não tem um funcionário AI atribuído. Atribua um antes de executar a ação. |
### Coerência owner ↔ executor (schedules)
| Code | HTTP | Descrição |
| ---------------- | ---- | --------------------------------------------------------------------------------------------------------------------- |
| `OWNER_MISMATCH` | 422 | O executor do scheduled message não coincide com o owner atual da conversa. Reatribua ou cancele o schedule primeiro. |
### Funcionários AI e execução
| Code | HTTP | Descrição |
| ------------------------------ | ---- | ------------------------------------------------------------------------------------------------------------- |
| `AI_EMPLOYEE_NOT_FOUND` | 404 | O funcionário AI não existe para este negócio. |
| `AMBIGUOUS_AI_EMPLOYEE` | 409 | Há vários funcionários com esse nome. Use `ai_employee_uuid` para desambiguar. |
| `AI_EMPLOYEE_ALREADY_ASSIGNED` | 409 | Esse funcionário AI já está atribuído à conversa. |
| `INVALID_ASSIGNEE_FOR_RUN_AI` | 409 | A conversa é human-owned e nenhum `ai_employee` foi especificado. Passe um ou reatribua um AI primeiro. |
| `AI_EXECUTION_FAILED` | 500 | A execução do AI falhou inesperadamente. Tente novamente; se persistir, verifique o dashboard do funcionário. |
| `ACTIONS_DEPTH_EXCEEDED` | 422 | Ações de AI encadeadas excedem a profundidade máxima permitida em uma requisição. |
### Scheduled message action
| Code | HTTP | Descrição |
| ----------------------------------- | ---- | ----------------------------------------------------------------------------------------------------------- |
| `SCHEDULED_MESSAGE_ACTION_REQUIRED` | 422 | Há um scheduled message ativo na conversa. Especifique `scheduled_message_action` (`reassign` ou `cancel`). |
| `SCHEDULED_MESSAGE_ACTION_INVALID` | 400 | O valor de `scheduled_message_action` é inválido. Deve ser `reassign` ou `cancel`. |
### Uploads
| Code | HTTP | Descrição |
| ------------------------------------ | ---- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| `INVALID_FILE_TYPE` | 400 | O tipo de arquivo não é permitido. Veja a documentação para a lista de MIME types aceitos. |
| `FILE_TOO_LARGE` | 400 | O arquivo excede o tamanho máximo para sua categoria. |
| `STORAGE_QUOTA_EXCEEDED` | 413 | O negócio atingiu sua cota de storage. Libere espaço ou faça upgrade do plano. |
| `STORAGE_QUOTA_CLEANUP_INSUFFICIENT` | 507 | O storage está cheio e a limpeza automática não conseguiu liberar espaço suficiente para este upload. Libere espaço ou faça upgrade do plano. |
| `FILE_NOT_FOUND` | 404 | Não existe arquivo com esse `file_uuid` para este negócio. |
| `FILE_NOT_UPLOADED` | 422 | O arquivo foi registrado mas o upload nunca foi confirmado. Re-suba antes de referenciá-lo. |
| `SIZE_MISMATCH` | 422 | O tamanho real do arquivo subido não coincide com o declarado em `request-upload`. |
| `MIME_MISMATCH` | 422 | O MIME type real não coincide com o declarado. Re-suba com o `Content-Type` correto. |
| `UPLOAD_FAILED` | 500 | O upload não pôde ser concluído por um erro de storage. Tente novamente. |
### Mensagens
| Code | HTTP | Descrição |
| --------------------- | ---- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `PREPARE_FAILED` | 500 | A mensagem não pôde ser preparada (erro de DB ou upstream). Tente novamente. |
| `SEND_FAILED` | 502 | O envio ao WhatsApp falhou. Verifique a saúde do canal e tente novamente. |
| `BSUID_SEND_DISABLED` | 409 | O contato não tem telefone e o envio pela sua identidade BSUID (business-scoped user ID) está desabilitado para este negócio. Use um contato com telefone ou habilite o envio por BSUID. |
### Quick replies e templates
| Code | HTTP | Descrição |
| -------------------------------------------- | ---- | ------------------------------------------------------------------------------------------------------------------------------------ |
| `QUICK_REPLY_NOT_FOUND` | 404 | A quick reply não existe para este negócio. |
| `QUICK_REPLY_AMBIGUOUS` | 409 | Há várias quick replies com esse nome. Use `quick_reply_uuid` para desambiguar. |
| `QUICK_REPLY_EMPTY` | 422 | A quick reply não tem ações configuradas. Adicione pelo menos uma no dashboard. |
| `TEMPLATE_NOT_FOUND` | 404 | O template não existe para este negócio. |
| `TEMPLATE_NOT_APPROVED` | 422 | O template não está aprovado pela Meta. Aprovação é requisito para envio. |
| `AUTH_TEMPLATE_REQUIRES_PHONE` | 409 | Não é possível enviar um template de autenticação a um contato sem telefone: a Meta exige o número. Envie a um contato com telefone. |
| `TEMPLATE_AMBIGUOUS` | 409 | Há vários templates com esse nome. Especifique `language` para desambiguar. |
| `TEMPLATE_VARIABLES_INVALID` | 422 | As variáveis do body não coincidem com o template (contagem incorreta, índice faltante ou valor vazio). |
| `TEMPLATE_HEADER_MISMATCH` | 400 | O tipo de header não coincide com o que o template declara (ex: template espera imagem e você enviou texto). |
| `TEMPLATE_FAKE_REQUIRES_TESTER_CONVERSATION` | 422 | O template é do módulo Tester (fake) e só pode ser enviado a conversas tester. |
### Operações genéricas
| Code | HTTP | Descrição |
| --------------- | ---- | -------------------------------------------------------------------------------------- |
| `FETCH_FAILED` | 500 | Não foi possível ler os dados necessários para concluir a requisição. Tente novamente. |
| `UPDATE_FAILED` | 500 | A alteração não pôde ser aplicada (erro de DB). Tente novamente. |
| `UNKNOWN_ERROR` | 500 | Erro inesperado. Contate o suporte se persistir. |