---
url: https://docs.ouvixpro.ai/guia/erros.md
description: >-
  Formato do erro, X-Request-Id e a tela Logs da API, códigos (400, 401, 404,
  410, 429, 500), limite de 60 chamadas por minuto e como tratar cada caso.
---

# Limites e erros

## Formato do erro

Toda resposta de erro tem status HTTP 4xx ou 5xx e um corpo JSON com o mesmo formato:

```json
{
  "error": {
    "message": "Informe de e ate no formato YYYY-MM-DD. Para um único dia, use a mesma data nos dois.",
    "type": "invalid_request_error",
    "code": "data_obrigatoria"
  }
}
```

| Campo | Uso |
| --- | --- |
| `code` | Identificador estável. Trate os erros por ele. |
| `type` | Família: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`. |
| `message` | Texto em português para registrar em log ou exibir a quem opera a integração. Pode mudar entre versões. |

## Rastreando uma chamada

Toda resposta — sucesso ou erro — traz o cabeçalho `X-Request-Id`, um identificador único da chamada. Guarde-o no seu log: é o mesmo id que aparece na tela **Logs da API** do OuvixPRO (menu da conta → *Logs da API*, ou a partir de *Chaves de API*).

Lá ficam as chamadas feitas com as suas chaves: status, código do erro, parâmetros, duração, tamanho e IP de origem, com filtros por período, status, endpoint e chave. Serve para conferir o que a integração está mandando sem precisar de acesso ao servidor. Chamadas sem chave válida (`401`) não são atribuídas a ninguém e não aparecem para o cliente.

```http
HTTP/1.1 400 Bad Request
X-Request-Id: be685b9c-2391-42d7-b591-46f8eaf895f3
```

## Códigos

### Autenticação e acesso

| HTTP | `code` | Causa |
| --- | --- | --- |
| 401 | `chave_ausente` | Cabeçalho `Authorization: Bearer` não enviado. |
| 401 | `chave_invalida` | Chave inexistente, digitada errado ou revogada. |
| 403 | `unidade_negada` | A chave não acessa o `Id_unidade` informado. |

### Parâmetros

| HTTP | `code` | Causa |
| --- | --- | --- |
| 400 | `id_unidade_obrigatoria` | `Id_unidade` não informado. |
| 400 | `id_unidade_invalida` | Caractere fora de letras, números, `_` e `-`, ou mais de 40 caracteres. |
| 400 | `data_obrigatoria` | `de` ou `ate` não informados. |
| 400 | `periodo_invalido` | Data inválida, `de` maior que `ate`, ou intervalo acima de 31 dias. |
| 400 | `turno_invalido` | Valor fora de `todos`, `manha`, `tarde`, `noite`. |
| 400 | `visao_desconhecida` | `visao` diferente de `recepcao` ou `professor`. |
| 400 | `tela_desconhecida` | `tela` em `/v1/tela` fora de `resumo`, `fluxo`, `qualidade`, `acesso`, `comercial`, `horarios`, `venda`, `renovacao`, `insights`. |
| 405 | `metodo` | Método diferente de `GET`. |

### Recurso não encontrado

| HTTP | `code` | Causa |
| --- | --- | --- |
| 404 | `unidade_nao_encontrada` | Nenhuma unidade com esse `Id_unidade`. |
| 404 | `visao_indisponivel` | `visao=professor` ainda não tem painel. |
| 404 | `atendimento_nao_encontrado` | O `id` não está nessa unidade e nesse período. |
| 404 | `audio_indisponivel` | O atendimento não tem trecho de gravação (`audio` é `null`). |
| 404 | `nao_encontrado` | Caminho inexistente. |
| 410 | `endpoint_removido` | Endpoint descontinuado (`/v1/audio`). A mensagem indica o substituto. |

### Limite e servidor

| HTTP | `code` | Causa |
| --- | --- | --- |
| 429 | `limite` | Mais de 60 chamadas por minuto com a mesma chave. Aguarde e repita. |
| 502 | `audio_indisponivel` | O armazenamento de áudio não respondeu ou o recorte falhou. |
| 500 | `servidor` | Falha interna. Repita com *backoff*; se persistir, informe o horário e o `Id_unidade` ao suporte. |

## Limites

| Limite | Valor |
| --- | --- |
| Intervalo por chamada | 31 dias |
| Requisições | 60 por minuto, por chave |
| Chaves ativas por conta | 20 |
| Tamanho de `Id_unidade` | 40 caracteres |

## Recomendações

* Trate `code`, não `message`.
* Faça cache do `/v1/painel` por período: os dados de um dia fechado não mudam.
* Em `429` e `5xx`, repita com espera crescente (por exemplo 1 s, 2 s, 4 s) e um teto de tentativas.
* Registre `Id_unidade`, `de`, `ate` e o horário da chamada junto com o erro; é o que o suporte precisa para investigar.