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óriocodestringObrigatórioerror.codeCódigo estável para tratamento programático.
messagestringObrigatórioerror.messageMensagem em pt-BR para exibição.
detailsobject[]Opcionalerror.detailsfieldstringObrigatórioerror.details[].fieldmessagestringObrigatórioerror.details[].messagecodestringObrigatórioerror.details[].coderequestIdstringObrigatórioerror.requestIdId 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.
{ "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
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.
- 400
bad_requestRequisição inválida.
- 400
invalid_clinic_idX-Clinic-Id inválido.
- 400
invalid_jsonCorpo JSON malformado.
- 400
invalid_multipartNão foi possível ler o envio. Tente de novo.
- 400
preflight_untrusted_fieldCampo não permitido no preflight.
- 400
tenant_context_requiredInforme a clínica ativa no cabeçalho X-Clinic-Id (você tem acesso a mais de uma clínica).
- 401
invalid_tokenToken ausente, inválido ou expirado.
- 401
unauthorizedAutenticação necessária.
- 402
trial_expiredO teste grátis terminou. O painel está em modo somente leitura até a ativação do plano.
- 403
agent_cannot_approveAprovar ou rejeitar a resposta é só de uma pessoa da clínica, no painel.
- 403
agent_context_mismatchAgente divergente do contexto autenticado.
- 403
agent_mismatchUm agente só publica as próprias execuções.
- 403
agent_not_enabledAgente não habilitado para esta clínica.
- 403
agent_only_fieldsPontuação e qualificação são definidas pelos agentes.
- 403
approval_requires_clinic_memberSó uma pessoa da própria clínica pode aprovar, editar ou concluir o perfil da clínica.
- 403
clinic_access_deniedVocê não tem acesso ativo a esta clínica.
- 403
clinic_admin_onlySomente um administrador da clínica confirma o WhatsApp de um usuário.
- 403
clinic_inactiveA clínica está com status SUSPENDED e não aceita operações.
- 403
clinic_member_onlyAs notificações são das pessoas da clínica.
- 403
clinic_member_requiredSó uma pessoa da própria clínica envia ou descarta anexos de conhecimento.
- 403
clinical_forbiddenCampos clínicos exigem permissão de prontuário.
- 403
cron_forbiddenSegredo do agendador inválido.
- 403
email_not_verifiedConfirme seu e-mail para continuar. Enviamos um link de verificação para a sua caixa de entrada.
- 403
forbiddenSeu perfil não tem permissão para esta ação.
- 403
handoff_onlyEste agente só pode transferir o lead para a equipe (HUMAN_HANDOFF).
- 403
human_onlyO acompanhamento ao vivo é para pessoas da clínica.
- 403
invitation_email_mismatchEste convite foi enviado para outro e-mail.
- 403
no_clinic_membershipVocê ainda não tem acesso ativo a nenhuma clínica.
- 403
orchestrator_not_enabledA orquestradora não está habilitada para esta clínica.
- 403
platform_onlySomente a equipe da plataforma.
- 403
preview_no_handoffConversas de Agent Preview não podem ser assumidas nem devolvidas.
- 403
preview_record_onlyRegistro sem envio permitido apenas em conversas de Agent Preview, e conversas de prévia só aceitam recordOnly do agente.
- 403
service_onlySessões de prévia só aceitam escrita do agente dono (token de serviço).
- 403
signup_not_allowedO autocadastro é feito pela conta do dono da clínica.
- 403
source_not_ownerA mensagem de origem não é do dono da clínica (WhatsApp verificado).
- 404
not_foundRecurso não encontrado.
- 404
route_not_foundRota … … não existe.
- 409
already_activeEsta automação já está ativa.
- 409
already_connectedIntegração já conectada. Desconecte antes de conectar outra conta.
- 409
already_convertedEste lead já virou paciente.
- 409
already_emittedEste atendimento já tem nota … (…).
- 409
already_memberEsta pessoa já tem acesso ou convite pendente nesta clínica.
- 409
attachment_already_downloadedEsta imagem já foi baixada. Cada imagem só pode ser baixada uma vez.
- 409
attachment_batch_closedO lote de anexos já foi encerrado.
- 409
awaiting_replyA Renata ainda está respondendo a mensagem anterior. Aguarde a resposta (ou use "tentar de novo").
- 409
cannot_change_own_accessVocê não pode alterar o próprio acesso.
- 409
change_closedEste pedido já foi encerrado.
- 409
change_expiredA confirmação passou do prazo. Apresente o pedido de novo.
- 409
change_in_progressEste pedido está sendo aprovado por outra pessoa. Atualize a tela.
- 409
change_supersededEste pedido foi substituído por outro mais recente.
- 409
class_fullTurma lotada: … de … vagas ocupadas neste horário.
- 409
concurrent_updateA assinatura foi criada por outra requisição. Tente de novo.
- 409
confirmation_question_mismatchA mensagem enviada ao dono não mostra o pedido como a API devolveu (valor, data e descrição por extenso). Apresente de novo.
- 409
confirmation_question_not_sentA pergunta de confirmação não foi enviada ao dono. Apresente o pedido de novo.
- 409
conflictMensagem específica da operação.
- 409
derived_already_setEsta mensagem já tem um derivado gravado com outro conteúdo.
- 409
draft_existsEste serviço já tem um rascunho aberto: edite-o ou descarte antes.
- 409
duplicateJá existe um serviço com a chave "…".
- 409
duplicate_sessionJá existe uma turma ativa neste serviço no mesmo dia e horário (…).
- 409
execution_agent_mismatchEsta execução pertence a outro agente.
- 409
idempotency_key_reusedEsta Idempotency-Key já foi usada com outro conteúdo.
- 409
ignoredCandidato marcado como "não emitir": restaure antes de revisar.
- 409
in_batchCandidato reservado num lote em rascunho: descarte o lote para revisar.
- 409
invalid_state_transitionMensagem específica da operação.
- 409
invitation_expiredConvite expirado. Peça um novo convite ao administrador.
- 409
invitation_not_pendingEste convite já foi usado ou cancelado.
- 409
label_limitA clínica já tem … etiquetas. Exclua uma antes de criar outra.
- 409
last_adminA clínica precisa de pelo menos um administrador ativo.
- 409
leave_production_firstEm Produção os dados fiscais não podem mudar. Volte para Homologação, altere e registre de novo a aprovação.
- 409
level_changedO nível já mudou (agora …). Releia e decida de novo.
- 409
message_has_no_mediaA mensagem não é uma mídia recebida.
- 409
onboarding_closedO onboarding desta clínica já foi concluído.
- 409
onboarding_disabledO onboarding com a Renata ainda não está disponível nesta clínica.
- 409
preview_identity_linkedSessão de prévia contém vínculo de contato ou atendimento humano.
- 409
same_planA clínica já está neste plano.
- 409
schedule_conflictConflito de agenda: o profissional já tem atendimento das … às ….
- 409
session_limitNo máximo … turmas por serviço.
- 409
signup_conflictNão foi possível concluir o cadastro. Fale com o suporte.
- 409
source_message_too_oldO pedido do dono é antigo. Peça para ele repetir.
- 409
stale_changeO registro mudou depois do pedido do dono. Ajuste direto na tela do registro.
- 409
stale_replyEste turno já terminou ou foi superado; descarte a resposta.
- 409
stream_capacityMuitas conexões ao vivo abertas. Tente de novo em instantes.
- 409
trial_not_cancellableDurante o teste grátis não há cobrança para cancelar: se não quiser continuar, basta não ativar o plano.
- 409
trial_unavailableO teste grátis já foi usado para esta automação.
- 409
upload_in_progressEste envio ainda está sendo gravado. Aguarde alguns segundos.
- 409
whatsapp_in_useEste WhatsApp já está cadastrado para outro usuário desta clínica.
- 409
whatsapp_missingCadastre o WhatsApp do usuário antes de confirmar.
- 413
payload_too_largeCorpo ou arquivo acima do limite.
- 415
unsupported_media_typeContent-Type não suportado.
- 422
agent_managed_by_onboardingO agente de onboarding é gerido pelo onboarding da clínica.
- 422
attachment_batch_not_availableO lote de anexos deste rascunho não existe nesta clínica, foi descartado ou venceu.
- 422
config_incompleteNão dá para aprovar uma configuração incompleta. Falta: ….
- 422
confirmation_not_affirmativeA mensagem não é uma confirmação escrita ("sim", "pode", "pode ser", "isso").
- 422
confirmation_requires_textConfirmação só vale por texto escrito (áudio, imagem ou outra mídia não confirmam).
- 422
delegate_not_enabledEspecialista não habilitado para esta clínica.
- 422
delegation_not_allowedSó a orquestradora (knowledge) registra trechos delegados.
- 422
draft_not_alloweddraftValue só é aceito com status aguardando_confirmacao.
- 422
draft_requiredInforme o valor extraído (draftValue) para aguardar a confirmação.
- 422
draft_too_largeO rascunho passa de … caracteres.
- 422
email_requiredA conta precisa ter um e-mail para criar a clínica.
- 422
event_mismatcheventId não corresponde ao evento da mensagem respondida.
- 422
fact_event_too_largeAs alterações deste fato excedem o tamanho máximo do registro.
- 422
idempotency_key_mismatchO cabeçalho Idempotency-Key precisa ser igual a clientMessageId.
- 422
invalid_cursorCursor inválido: use o id de uma mensagem desta sessão.
- 422
invalid_phoneNúmero de WhatsApp inválido.
- 422
invalid_source_messagesource_message_id precisa ser uma mensagem recebida nesta clínica.
- 422
key_not_allowed_for_questionEsta pergunta não preenche essa chave.
- 422
kind_not_directEste tipo de dado não é gravado direto: siga pelo caminho de proposta para aprovação no painel.
- 422
looks_like_personal_dataO 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.
- 422
missing_fieldsFaltam dados para …: ….
- 422
not_undoableEsta operação não se desfaz por aqui.
- 422
nothing_to_changeA duração informada já é a cadastrada.
- 422
operation_not_in_domainOperação fora deste domínio.
- 422
operation_not_supportedOperação sem executor.
- 422
path_not_allowed_for_questionEsse caminho não é preenchido por esta pergunta.
- 422
path_requiredEsta pergunta preenche um campo da chave: envie `path` com só a sub-resposta (o valor inteiro da chave não é trocado).
- 422
plan_requires_salesEste plano é sob consulta e não está disponível no autocadastro. Fale com o time comercial.
- 422
production_confirmation_requiredPara ativar Produção digite exatamente: …
- 422
question_retiredA pergunta … foi aposentada. Use ….
- 422
reason_requiredInforme o motivo da rejeição.
- 422
rule_incompleteRegra incompleta para aprovar: ….
- 422
source_message_requiredInforme a mensagem do dono que sustenta a resposta (sourceMessageId).
- 422
target_ref_requiredInforme o fato ou artigo criado (targetRef) ao propor.
- 422
too_many_filesEnvie no máximo … imagens por vez.
- 422
too_many_price_optionsO serviço já tem … opções de preço. Remova alguma no painel.
- 422
unknown_clinicClínica inexistente.
- 422
unknown_fact_keyChave desconhecida. Use: ….
- 422
unknown_planPlano inexistente.
- 422
unknown_professionalProfissional não encontrado nesta clínica.
- 422
unknown_questionPergunta desconhecida no catálogo.
- 422
unknown_serviceServiço não encontrado (ou inativo) nesta clínica.
- 422
unprocessable_entityMensagem específica da operação.
- 422
unsafe_svgSVG com scripts ou conteúdo ativo não é aceito.
- 422
unsupported_file_typeFormato não suportado. Use PNG, JPEG, WEBP ou SVG.
- 422
use_convertPara "Virou paciente" use POST /leads/{id}/convert (cria o cadastro do paciente).
- 422
validation_errorA validação da requisição falhou.
- 422
version_mismatchIf-Match e version têm valores diferentes.
- 422
version_requiredInforme a versão da chave lida (If-Match ou version).
- 422
wrong_confirm_routeEste pedido se confirma pela rota própria (confirmRoute).
- 429
rate_limit_exceededLimite de requisições excedido. Tente novamente em … segundos.
- 500
internal_errorErro interno. Informe o requestId ao suporte.
- 502
upstream_errorUm serviço externo falhou.
- 503
backend_unavailableO armazenamento de dados da plataforma não está configurado ou não respondeu.
- 503
signup_disabledO cadastro de novas clínicas ainda não está aberto. Fale com a equipe do My Clinic.
- 504
upstream_timeoutO 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.