Códigos de erro e estratégia

A API OTIMUS não tem documentação pública oficial. Esta página lista erros observados em produção e como tratar.

HTTP status

Status	Significado observado	Ação
200	Sucesso — mas leia data, pode ser string de erro	Parse defensivo
400	Payload mal-formado	Log + transferir para humano
401	Token inválido ou sistema ausente	Alerta crítico, parar chamadas até rotacionar
404	Endpoint desconhecido ou clínica errada	Revisar OTIMUS_API_URL
5xx	OTIMUS indisponível	Retry até 2x, depois FALHA_CONSULTA

Erros "200 com payload de erro"

O OTIMUS às vezes responde 200 OK com data sendo uma string de erro. Os conhecidos:

data value	Endpoint	Interpretação
"O CPF informado não foi encontrado."	/cadastros/pacientes/cpf/{cpf}	Paciente não existe (normal)
[]	/agendamento/horarios	Agenda sem disponibilidade

Timeouts

Timeout padrão: 30s. Em MEDCENTER o cliente faz 2 tentativas antes de falhar:

# scheduling.py:196+ (padrão)
def _chamar_api_horarios(payload: dict, tentativas: int = 2) -> list | None:
    for i in range(tentativas):
        try:
            resp = requests.post(url, headers=_otimus_headers(), json=payload, timeout=30)
            resp.raise_for_status()
            return resp.json().get("data", [])
        except Exception as e:
            logger.warning("OTIMUS /horarios tentativa %d falhou: %s", i + 1, e)
    return None

Contrato FALHA_CONSULTA

Quando o cliente OTIMUS falha por qualquer motivo (timeout, 5xx, dados inconsistentes, validação de agendaNome), a função retorna uma string que começa com FALHA_CONSULTA:.

O agente é instruído (via system prompt) a:

1. Nunca inventar horários.
2. Não repetir a chamada.
3. Transferir para humano usando transferir_atendimento(motivo).

Exemplos de strings de falha:

FALHA_CONSULTA: medico 'Fulano' nao possui agendamento automatico
FALHA_CONSULTA: convenio nao encontrado: Bradesco Prime
FALHA_CONSULTA: procedimento 'USG de pé' nao encontrado
FALHA_CONSULTA: agenda sem horarios disponiveis
FALHA_CONSULTA: erro ao consultar horarios apos 2 tentativas
FALHA_CONSULTA: erro interno: Connection refused

Ver FALHA_CONSULTA para o tratamento no agente.

Validação de agendaNome falhou

Se agendaNome não contém o primeiro nome do médico esperado, o cliente trata como falha:

# scheduling.py:157-188 (MEDCENTER)
if check_token not in agenda_nome:
    logger.error(
        "VALIDACAO FALHOU: agendaNome='%s' nao contem '%s' (medico esperado: %s)",
        agenda_nome_raw, check_token, medico_esperado,
    )
    return False

O motivo é evitar falso positivo — se o OTIMUS devolver a agenda errada, o paciente não pode ser agendado com o médico errado.

Observabilidade mínima

Toda falha de OTIMUS deve gerar:

1. Log ERROR com endpoint e payload.

2. Registro em dashboard_errors via log_error():

   log_error(
       error_type="otimus_error",
       error_message=f"{endpoint}: {exc}",
       session_id=session_id,
       phone_number=phone,
   )