Pular para o conteúdo

Tratamento de erros

Todo erro tem o mesmo formato. Trate pelo código estável em error.code, mostre error.message e guarde o requestId.

Formato do erro

Campos do objeto error (esquema Error do contrato):

  • errorobjectObrigatório
  • codestringObrigatório
    error.code

    Código estável para tratamento programático.

  • messagestringObrigatório
    error.message

    Mensagem em pt-BR para exibição.

  • detailsobject[]Opcional
    error.details
  • fieldstringObrigatório
    error.details[].field
  • messagestringObrigatório
    error.details[].message
  • codestringObrigatório
    error.details[].code
  • requestIdstringObrigatório
    error.requestId

    Id da requisição (também no cabeçalho X-Request-Id). Informe ao suporte.

Erros de validação

Corpo, consulta ou caminho fora do esquema devolvem 422 com um item em details por problema. A mensagem de cada item vem do validador e hoje sai em inglês; use field e code para montar o texto na sua interface.

422 Unprocessable Entity
{  "error": {    "code": "validation_error",    "message": "A validação da requisição falhou.",    "details": [      {        "field": "name",        "message": "must have required property 'name'",        "code": "required"      }    ],    "requestId": "req_3f9c1a7b2d4e6f8a0b1c"  }}

Status HTTP

400
Bad Request — Requisição malformada: JSON inválido, cursor inválido ou clínica ativa não informada.
401
Unauthorized — Token ausente, inválido ou expirado.
403
Forbidden — Autenticado, mas sem permissão (perfil ou clínica).
404
Not Found — Recurso ou rota inexistente — ou de outra clínica (a API não revela se existe).
409
Conflict — Conflito de estado: duplicado, transição inválida, horário ocupado.
422
Unprocessable Entity — Dados semanticamente inválidos; erros por campo em details.
429
Too Many Requests — Limite de requisições excedido; veja Retry-After.
500
Internal Server Error — Erro interno, sem detalhes expostos. Informe o requestId.
502
Bad Gateway — Um serviço externo falhou.
503
Service Unavailable — Armazenamento de dados indisponível; tente de novo após Retry-After.

Códigos de erro

Lista extraída do código da API (145 códigos). “Mensagem específica da operação” indica que o texto muda conforme o caso.

  • 400bad_request

    Requisição inválida.

  • 400invalid_clinic_id

    X-Clinic-Id inválido.

  • 400invalid_json

    Corpo JSON malformado.

  • 400invalid_multipart

    Não foi possível ler o envio. Tente de novo.

  • 400preflight_untrusted_field

    Campo não permitido no preflight.

  • 400tenant_context_required

    Informe a clínica ativa no cabeçalho X-Clinic-Id (você tem acesso a mais de uma clínica).

  • 401invalid_token

    Token ausente, inválido ou expirado.

  • 401unauthorized

    Autenticação necessária.

  • 402trial_expired

    O teste grátis terminou. O painel está em modo somente leitura até a ativação do plano.

  • 403agent_cannot_approve

    Aprovar ou rejeitar a resposta é só de uma pessoa da clínica, no painel.

  • 403agent_context_mismatch

    Agente divergente do contexto autenticado.

  • 403agent_mismatch

    Um agente só publica as próprias execuções.

  • 403agent_not_enabled

    Agente não habilitado para esta clínica.

  • 403agent_only_fields

    Pontuação e qualificação são definidas pelos agentes.

  • 403approval_requires_clinic_member

    Só uma pessoa da própria clínica pode aprovar, editar ou concluir o perfil da clínica.

  • 403clinic_access_denied

    Você não tem acesso ativo a esta clínica.

  • 403clinic_admin_only

    Somente um administrador da clínica confirma o WhatsApp de um usuário.

  • 403clinic_inactive

    A clínica está com status SUSPENDED e não aceita operações.

  • 403clinic_member_only

    As notificações são das pessoas da clínica.

  • 403clinic_member_required

    Só uma pessoa da própria clínica envia ou descarta anexos de conhecimento.

  • 403clinical_forbidden

    Campos clínicos exigem permissão de prontuário.

  • 403cron_forbidden

    Segredo do agendador inválido.

  • 403email_not_verified

    Confirme seu e-mail para continuar. Enviamos um link de verificação para a sua caixa de entrada.

  • 403forbidden

    Seu perfil não tem permissão para esta ação.

  • 403handoff_only

    Este agente só pode transferir o lead para a equipe (HUMAN_HANDOFF).

  • 403human_only

    O acompanhamento ao vivo é para pessoas da clínica.

  • 403invitation_email_mismatch

    Este convite foi enviado para outro e-mail.

  • 403no_clinic_membership

    Você ainda não tem acesso ativo a nenhuma clínica.

  • 403orchestrator_not_enabled

    A orquestradora não está habilitada para esta clínica.

  • 403platform_only

    Somente a equipe da plataforma.

  • 403preview_no_handoff

    Conversas de Agent Preview não podem ser assumidas nem devolvidas.

  • 403preview_record_only

    Registro sem envio permitido apenas em conversas de Agent Preview, e conversas de prévia só aceitam recordOnly do agente.

  • 403service_only

    Sessões de prévia só aceitam escrita do agente dono (token de serviço).

  • 403signup_not_allowed

    O autocadastro é feito pela conta do dono da clínica.

  • 403source_not_owner

    A mensagem de origem não é do dono da clínica (WhatsApp verificado).

  • 404not_found

    Recurso não encontrado.

  • 404route_not_found

    Rota … … não existe.

  • 409already_active

    Esta automação já está ativa.

  • 409already_connected

    Integração já conectada. Desconecte antes de conectar outra conta.

  • 409already_converted

    Este lead já virou paciente.

  • 409already_emitted

    Este atendimento já tem nota … (…).

  • 409already_member

    Esta pessoa já tem acesso ou convite pendente nesta clínica.

  • 409attachment_already_downloaded

    Esta imagem já foi baixada. Cada imagem só pode ser baixada uma vez.

  • 409attachment_batch_closed

    O lote de anexos já foi encerrado.

  • 409awaiting_reply

    A Renata ainda está respondendo a mensagem anterior. Aguarde a resposta (ou use "tentar de novo").

  • 409cannot_change_own_access

    Você não pode alterar o próprio acesso.

  • 409change_closed

    Este pedido já foi encerrado.

  • 409change_expired

    A confirmação passou do prazo. Apresente o pedido de novo.

  • 409change_in_progress

    Este pedido está sendo aprovado por outra pessoa. Atualize a tela.

  • 409change_superseded

    Este pedido foi substituído por outro mais recente.

  • 409class_full

    Turma lotada: … de … vagas ocupadas neste horário.

  • 409concurrent_update

    A assinatura foi criada por outra requisição. Tente de novo.

  • 409confirmation_question_mismatch

    A mensagem enviada ao dono não mostra o pedido como a API devolveu (valor, data e descrição por extenso). Apresente de novo.

  • 409confirmation_question_not_sent

    A pergunta de confirmação não foi enviada ao dono. Apresente o pedido de novo.

  • 409conflict

    Mensagem específica da operação.

  • 409derived_already_set

    Esta mensagem já tem um derivado gravado com outro conteúdo.

  • 409draft_exists

    Este serviço já tem um rascunho aberto: edite-o ou descarte antes.

  • 409duplicate

    Já existe um serviço com a chave "…".

  • 409duplicate_session

    Já existe uma turma ativa neste serviço no mesmo dia e horário (…).

  • 409execution_agent_mismatch

    Esta execução pertence a outro agente.

  • 409idempotency_key_reused

    Esta Idempotency-Key já foi usada com outro conteúdo.

  • 409ignored

    Candidato marcado como "não emitir": restaure antes de revisar.

  • 409in_batch

    Candidato reservado num lote em rascunho: descarte o lote para revisar.

  • 409invalid_state_transition

    Mensagem específica da operação.

  • 409invitation_expired

    Convite expirado. Peça um novo convite ao administrador.

  • 409invitation_not_pending

    Este convite já foi usado ou cancelado.

  • 409label_limit

    A clínica já tem … etiquetas. Exclua uma antes de criar outra.

  • 409last_admin

    A clínica precisa de pelo menos um administrador ativo.

  • 409leave_production_first

    Em Produção os dados fiscais não podem mudar. Volte para Homologação, altere e registre de novo a aprovação.

  • 409level_changed

    O nível já mudou (agora …). Releia e decida de novo.

  • 409message_has_no_media

    A mensagem não é uma mídia recebida.

  • 409onboarding_closed

    O onboarding desta clínica já foi concluído.

  • 409onboarding_disabled

    O onboarding com a Renata ainda não está disponível nesta clínica.

  • 409preview_identity_linked

    Sessão de prévia contém vínculo de contato ou atendimento humano.

  • 409same_plan

    A clínica já está neste plano.

  • 409schedule_conflict

    Conflito de agenda: o profissional já tem atendimento das … às ….

  • 409session_limit

    No máximo … turmas por serviço.

  • 409signup_conflict

    Não foi possível concluir o cadastro. Fale com o suporte.

  • 409source_message_too_old

    O pedido do dono é antigo. Peça para ele repetir.

  • 409stale_change

    O registro mudou depois do pedido do dono. Ajuste direto na tela do registro.

  • 409stale_reply

    Este turno já terminou ou foi superado; descarte a resposta.

  • 409stream_capacity

    Muitas conexões ao vivo abertas. Tente de novo em instantes.

  • 409trial_not_cancellable

    Durante o teste grátis não há cobrança para cancelar: se não quiser continuar, basta não ativar o plano.

  • 409trial_unavailable

    O teste grátis já foi usado para esta automação.

  • 409upload_in_progress

    Este envio ainda está sendo gravado. Aguarde alguns segundos.

  • 409whatsapp_in_use

    Este WhatsApp já está cadastrado para outro usuário desta clínica.

  • 409whatsapp_missing

    Cadastre o WhatsApp do usuário antes de confirmar.

  • 413payload_too_large

    Corpo ou arquivo acima do limite.

  • 415unsupported_media_type

    Content-Type não suportado.

  • 422agent_managed_by_onboarding

    O agente de onboarding é gerido pelo onboarding da clínica.

  • 422attachment_batch_not_available

    O lote de anexos deste rascunho não existe nesta clínica, foi descartado ou venceu.

  • 422config_incomplete

    Não dá para aprovar uma configuração incompleta. Falta: ….

  • 422confirmation_not_affirmative

    A mensagem não é uma confirmação escrita ("sim", "pode", "pode ser", "isso").

  • 422confirmation_requires_text

    Confirmação só vale por texto escrito (áudio, imagem ou outra mídia não confirmam).

  • 422delegate_not_enabled

    Especialista não habilitado para esta clínica.

  • 422delegation_not_allowed

    Só a orquestradora (knowledge) registra trechos delegados.

  • 422draft_not_allowed

    draftValue só é aceito com status aguardando_confirmacao.

  • 422draft_required

    Informe o valor extraído (draftValue) para aguardar a confirmação.

  • 422draft_too_large

    O rascunho passa de … caracteres.

  • 422email_required

    A conta precisa ter um e-mail para criar a clínica.

  • 422event_mismatch

    eventId não corresponde ao evento da mensagem respondida.

  • 422fact_event_too_large

    As alterações deste fato excedem o tamanho máximo do registro.

  • 422idempotency_key_mismatch

    O cabeçalho Idempotency-Key precisa ser igual a clientMessageId.

  • 422invalid_cursor

    Cursor inválido: use o id de uma mensagem desta sessão.

  • 422invalid_phone

    Número de WhatsApp inválido.

  • 422invalid_source_message

    source_message_id precisa ser uma mensagem recebida nesta clínica.

  • 422key_not_allowed_for_question

    Esta pergunta não preenche essa chave.

  • 422kind_not_direct

    Este tipo de dado não é gravado direto: siga pelo caminho de proposta para aprovação no painel.

  • 422looks_like_personal_data

    O valor parece ter dado de pessoa física (CPF, CNS ou nascimento com nome). O perfil da clínica não guarda dados de pessoas.

  • 422missing_fields

    Faltam dados para …: ….

  • 422not_undoable

    Esta operação não se desfaz por aqui.

  • 422nothing_to_change

    A duração informada já é a cadastrada.

  • 422operation_not_in_domain

    Operação fora deste domínio.

  • 422operation_not_supported

    Operação sem executor.

  • 422path_not_allowed_for_question

    Esse caminho não é preenchido por esta pergunta.

  • 422path_required

    Esta pergunta preenche um campo da chave: envie `path` com só a sub-resposta (o valor inteiro da chave não é trocado).

  • 422plan_requires_sales

    Este plano é sob consulta e não está disponível no autocadastro. Fale com o time comercial.

  • 422production_confirmation_required

    Para ativar Produção digite exatamente: …

  • 422question_retired

    A pergunta … foi aposentada. Use ….

  • 422reason_required

    Informe o motivo da rejeição.

  • 422rule_incomplete

    Regra incompleta para aprovar: ….

  • 422source_message_required

    Informe a mensagem do dono que sustenta a resposta (sourceMessageId).

  • 422target_ref_required

    Informe o fato ou artigo criado (targetRef) ao propor.

  • 422too_many_files

    Envie no máximo … imagens por vez.

  • 422too_many_price_options

    O serviço já tem … opções de preço. Remova alguma no painel.

  • 422unknown_clinic

    Clínica inexistente.

  • 422unknown_fact_key

    Chave desconhecida. Use: ….

  • 422unknown_plan

    Plano inexistente.

  • 422unknown_professional

    Profissional não encontrado nesta clínica.

  • 422unknown_question

    Pergunta desconhecida no catálogo.

  • 422unknown_service

    Serviço não encontrado (ou inativo) nesta clínica.

  • 422unprocessable_entity

    Mensagem específica da operação.

  • 422unsafe_svg

    SVG com scripts ou conteúdo ativo não é aceito.

  • 422unsupported_file_type

    Formato não suportado. Use PNG, JPEG, WEBP ou SVG.

  • 422use_convert

    Para "Virou paciente" use POST /leads/{id}/convert (cria o cadastro do paciente).

  • 422validation_error

    A validação da requisição falhou.

  • 422version_mismatch

    If-Match e version têm valores diferentes.

  • 422version_required

    Informe a versão da chave lida (If-Match ou version).

  • 422wrong_confirm_route

    Este pedido se confirma pela rota própria (confirmRoute).

  • 429rate_limit_exceeded

    Limite de requisições excedido. Tente novamente em … segundos.

  • 500internal_error

    Erro interno. Informe o requestId ao suporte.

  • 502upstream_error

    Um serviço externo falhou.

  • 503backend_unavailable

    O armazenamento de dados da plataforma não está configurado ou não respondeu.

  • 503signup_disabled

    O cadastro de novas clínicas ainda não está aberto. Fale com a equipe do My Clinic.

  • 504upstream_timeout

    O armazenamento de dados demorou demais para responder. Tente novamente em instantes.

Como tratar

  • Decida pelo status e por error.code; o texto de message pode mudar.
  • 401: renove o token e repita uma única vez. 403: não repita — falta permissão ou vínculo.
  • 429 e 503: espere o Retry-After antes de tentar de novo.
  • 409: releia o recurso; o estado mudou desde a sua última leitura.
  • Registre o requestId (também no cabeçalho X-Request-Id) e envie ao suporte quando precisar de ajuda.
Rotas inexistentes respondem 404 com o código route_not_found, no mesmo formato.