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):

Campos do erro
Parâmetro	Tipo	Obrigatório	Descrição
`error`	object	Sim	—
`code` error.code	string	Sim	Código estável para tratamento programático.
`message` error.message	string	Sim	Mensagem em pt-BR para exibição.
`details` error.details	object[]	Não	—
`field` error.details[].field	string	Sim	—
`message` error.details[].message	string	Sim	—
`code` error.details[].code	string	Sim	—
`requestId` error.requestId	string	Sim	Id da requisição (também no cabeçalho X-Request-Id). Informe ao suporte.

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

1{2  "error": {3    "code": "validation_error",4    "message": "A validação da requisição falhou.",5    "details": [6      {7        "field": "name",8        "message": "must have required property 'name'",9        "code": "required"10      }11    ],12    "requestId": "req_3f9c1a7b2d4e6f8a0b1c"13  }14}

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 (71 códigos). “Mensagem específica da operação” indica que o texto muda conforme o caso.

Status	error.code	Mensagem
400	`bad_request`	Requisição inválida.
400	`invalid_clinic_id`	X-Clinic-Id inválido.
400	`invalid_json`	Corpo JSON malformado.
400	`preflight_untrusted_field`	Campo não permitido no preflight.
400	`tenant_context_required`	Informe a clínica ativa no cabeçalho X-Clinic-Id (você tem acesso a mais de uma clínica).
401	`invalid_token`	Token ausente, inválido ou expirado.
401	`unauthorized`	Autenticação necessária.
402	`trial_expired`	O teste grátis terminou. O painel está em modo somente leitura até a ativação do plano.
403	`agent_context_mismatch`	Agente divergente do contexto autenticado.
403	`agent_mismatch`	Um agente só registra execuções/estado próprios.
403	`agent_not_enabled`	Agente não habilitado para esta clínica.
403	`agent_only_fields`	Pontuação e qualificação são definidas pelos agentes.
403	`clinic_access_denied`	Você não tem acesso ativo a esta clínica.
403	`clinic_inactive`	A clínica está com status SUSPENDED e não aceita operações.
403	`clinical_forbidden`	Campos clínicos exigem permissão de prontuário.
403	`cron_forbidden`	Segredo do agendador inválido.
403	`email_not_verified`	Confirme seu e-mail para continuar. Enviamos um link de verificação para a sua caixa de entrada.
403	`forbidden`	Seu perfil não tem permissão para esta ação.
403	`invitation_email_mismatch`	Este convite foi enviado para outro e-mail.
403	`no_clinic_membership`	Você ainda não tem acesso ativo a nenhuma clínica.
403	`platform_only`	Somente a equipe da plataforma.
403	`preview_no_handoff`	Conversas de Agent Preview não podem ser assumidas nem devolvidas.
403	`preview_record_only`	Registro sem envio permitido apenas em conversas de Agent Preview, e conversas de prévia só aceitam recordOnly do agente.
403	`service_only`	Sessões de prévia só aceitam escrita do agente dono (token de serviço).
403	`signup_not_allowed`	O autocadastro é feito pela conta do dono da clínica.
404	`not_found`	Recurso não encontrado.
404	`route_not_found`	Rota … … não existe.
409	`already_active`	Esta automação já está ativa.
409	`already_connected`	Integração já conectada. Desconecte antes de conectar outra conta.
409	`already_converted`	Este lead já virou paciente.
409	`already_emitted`	Este atendimento já tem nota … (…).
409	`already_member`	Esta pessoa já tem acesso ou convite pendente nesta clínica.
409	`cannot_change_own_access`	Você não pode alterar o próprio acesso.
409	`concurrent_update`	A assinatura foi criada por outra requisição. Tente de novo.
409	`conflict`	Mensagem específica da operação.
409	`draft_exists`	Este serviço já tem um rascunho aberto: edite-o ou descarte antes.
409	`duplicate`	Já existe um serviço com a chave "…".
409	`idempotency_key_reused`	Esta Idempotency-Key já foi usada com outro conteúdo.
409	`ignored`	Candidato marcado como "não emitir": restaure antes de revisar.
409	`in_batch`	Candidato reservado num lote em rascunho: descarte o lote para revisar.
409	`invalid_state_transition`	Mensagem específica da operação.
409	`invitation_expired`	Convite expirado. Peça um novo convite ao administrador.
409	`invitation_not_pending`	Este convite já foi usado ou cancelado.
409	`label_limit`	A clínica já tem … etiquetas. Exclua uma antes de criar outra.
409	`last_admin`	A clínica precisa de pelo menos um administrador ativo.
409	`leave_production_first`	Em Produção os dados fiscais não podem mudar. Volte para Homologação, altere e registre de novo a aprovação.
409	`preview_identity_linked`	Sessão de prévia contém vínculo de contato ou atendimento humano.
409	`same_plan`	A clínica já está neste plano.
409	`schedule_conflict`	Conflito de agenda: o profissional já tem atendimento das … às ….
409	`signup_conflict`	Não foi possível concluir o cadastro. Fale com o suporte.
409	`trial_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.
409	`trial_unavailable`	O teste grátis já foi usado para esta automação.
413	`payload_too_large`	Corpo ou arquivo acima do limite.
415	`unsupported_media_type`	Content-Type não suportado.
422	`config_incomplete`	Não dá para aprovar uma configuração incompleta. Falta: ….
422	`email_required`	A conta precisa ter um e-mail para criar a clínica.
422	`plan_requires_sales`	Este plano é sob consulta e não está disponível no autocadastro. Fale com o time comercial.
422	`production_confirmation_required`	Para ativar Produção digite exatamente: …
422	`rule_incomplete`	Regra incompleta para aprovar: ….
422	`unknown_plan`	Plano inexistente.
422	`unknown_professional`	Profissional não encontrado nesta clínica.
422	`unprocessable_entity`	Mensagem específica da operação.
422	`unsafe_svg`	SVG com scripts ou conteúdo ativo não é aceito.
422	`unsupported_file_type`	Formato não suportado. Use PNG, JPEG, WEBP ou SVG.
422	`use_convert`	Para "Virou paciente" use POST /leads/{id}/convert (cria o cadastro do paciente).
422	`validation_error`	A validação da requisição falhou.
429	`rate_limit_exceeded`	Limite de requisições excedido. Tente novamente em … segundos.
500	`internal_error`	Erro interno. Informe o requestId ao suporte.
502	`upstream_error`	Um serviço externo falhou.
503	`backend_unavailable`	O armazenamento de dados da plataforma não está configurado ou não respondeu.
503	`signup_disabled`	O cadastro de novas clínicas ainda não está aberto. Fale com a equipe do My Clinic.

400bad_request
Requisição inválida.
400invalid_clinic_id
X-Clinic-Id inválido.
400invalid_json
Corpo JSON malformado.
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_context_mismatch
Agente divergente do contexto autenticado.
403agent_mismatch
Um agente só registra execuções/estado próprios.
403agent_not_enabled
Agente não habilitado para esta clínica.
403agent_only_fields
Pontuação e qualificação são definidas pelos agentes.
403clinic_access_denied
Você não tem acesso ativo a esta clínica.
403clinic_inactive
A clínica está com status SUSPENDED e não aceita operações.
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.
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.
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.
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.
409cannot_change_own_access
Você não pode alterar o próprio acesso.
409concurrent_update
A assinatura foi criada por outra requisição. Tente de novo.
409conflict
Mensagem específica da operação.
409draft_exists
Este serviço já tem um rascunho aberto: edite-o ou descarte antes.
409duplicate
Já existe um serviço com a chave "…".
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.
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 ….
409signup_conflict
Não foi possível concluir o cadastro. Fale com o suporte.
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.
413payload_too_large
Corpo ou arquivo acima do limite.
415unsupported_media_type
Content-Type não suportado.
422config_incomplete
Não dá para aprovar uma configuração incompleta. Falta: ….
422email_required
A conta precisa ter um e-mail para criar a clínica.
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: …
422rule_incomplete
Regra incompleta para aprovar: ….
422unknown_plan
Plano inexistente.
422unknown_professional
Profissional não encontrado 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.
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.

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.