Limites e erros

Formato do erro

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

{
  "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/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.