> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://api-docs.nilo.services/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://api-docs.nilo.services/_mcp/server. # Como diagnosticar > As cinco checagens que resolvem a maior parte dos erros de integração, e o índice das mensagens de erro conhecidas. Esta seção reúne os problemas que mais aparecem em integrações reais: o **sintoma** como ele chega, a **causa** e o **que fazer**. Ela não substitui a página de cada recurso — quando o problema é um campo específico, o lugar certo é a tabela de campos do recurso. Serve para o caso oposto: você tem uma mensagem de erro, ou um recurso que foi aceito e não apareceu, e precisa saber por onde começar. ## Cinco checagens antes de tudo A maioria dos casos que chegam ao suporte cai em um destes cinco padrões. Vale passar por eles antes de procurar o caso específico. **1. Leia o `OperationOutcome`.** Toda escrita recusada volta com um diagnóstico que nomeia o campo. Numa [carga em lote](/guia/operacoes/carga-em-lote), a entrada que falhou volta identificada pelo `fullUrl` — e quando o que falhou foi uma dependência, a mensagem diz o `fullUrl` do recurso que precisa ser corrigido, não o do recurso que você estava tentando gravar. **2. Confirme o ambiente.** Os `system` de identificador de paciente e de profissional são configurados por ambiente, e os ids internos da plataforma — planos de saúde, grupos de pacientes, status, campanhas, unidades de cuidado — **não são os mesmos** em homologação e em produção. Um payload que funciona em um ambiente pode falhar no outro sem que nada esteja errado nele. Confirme também que o paciente que você está referenciando existe no ambiente em que você está enviando. **3. Confirme que o que você referencia já existe.** Referência por identificador não cria nada. Se o paciente, o profissional, o atendimento, o plano de saúde ou o grupo apontado não estiver cadastrado naquele ambiente, a escrita é recusada — e o erro fala do recurso referenciado, não do que você enviou. **4. Verifique se houve envio duplicado.** Duas requisições iguais para o mesmo recurso em sequência rápida é uma das causas mais frequentes de erro: a primeira grava, e a segunda falha porque o registro já está no estado final. Antes de tratar como bug, confira se a primeira das duas foi aceita — em geral foi, e não há nada a corrigir além do reenvio. **5. Considere o tempo de propagação.** Um `200` diz que a escrita foi aceita, não que ela já está visível. Parte do que você envia passa por processamento assíncrono, algumas atribuições rodam em lote uma vez por dia, e algumas telas leem de um cache de poucos minutos. Antes de reenviar, confirme por um `GET` se o recurso está lá. > **Note** > > Reenviar não é perigoso — a escrita é um [upsert por identificador](/guia/comecando/escritas), então o mesmo payload enviado duas vezes atualiza o > mesmo registro em vez de criar dois. O que causa problema é reenviar **em paralelo**: dois > envios simultâneos do mesmo recurso disputam o mesmo registro e um dos dois falha. ## Índice de mensagens de erro | Mensagem | Onde está o caso | | ----------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- | | `Unable to use any of the provided identifiers to match an existing resource` | [Identificadores e duplicidade](/guia/solucao-de-problemas/identificadores) | | `No identifier systems configured` | [Configuração e ambientes](/guia/solucao-de-problemas/configuracao) | | `MultipleResourcesReturned: Too many matches` | [Identificadores e duplicidade](/guia/solucao-de-problemas/identificadores) | | `returned more than one resource` | [Identificadores e duplicidade](/guia/solucao-de-problemas/identificadores) | | `Reference … not found` | [Identificadores e duplicidade](/guia/solucao-de-problemas/identificadores) | | `Invalid CPF: must contain exactly 11 digits` | [Identificadores e duplicidade](/guia/solucao-de-problemas/identificadores) | | `Wrong ResourceType: … expects … but got Bundle` | [Ordem de envio e processamento](/guia/solucao-de-problemas/ordem-de-envio) | | `Resource dependencies not processed successfully` | [Ordem de envio e processamento](/guia/solucao-de-problemas/ordem-de-envio) | | `Dependency … not processed successfully` | [Ordem de envio e processamento](/guia/solucao-de-problemas/ordem-de-envio) | | `value is not a valid list` | [Ordem de envio e processamento](/guia/solucao-de-problemas/ordem-de-envio) | | `429 Too Many Requests` | [Ordem de envio e processamento](/guia/solucao-de-problemas/ordem-de-envio) | | `CarePlan with status revoked can't be updated` | [Diretrizes](/guia/solucao-de-problemas/diretrizes) | | `CarePlan can't be updated to status draft` | [Diretrizes](/guia/solucao-de-problemas/diretrizes) | | `Only Practitioner/Patient type is supported` | [Diretrizes](/guia/solucao-de-problemas/diretrizes) | | `does not point to an active care line` | [Diretrizes](/guia/solucao-de-problemas/diretrizes) | | `Too many matches for Practitioner` | [Equipe de cuidado e profissionais](/guia/solucao-de-problemas/equipe-e-profissionais) | | `Encounter does not exist` | [Atendimentos e agendamento](/guia/solucao-de-problemas/atendimentos) | | `Unable to locate Nilo model for the resource` | [Atendimentos e agendamento](/guia/solucao-de-problemas/atendimentos) | | `Period is required to create inactive flags` | [Atendimentos e agendamento](/guia/solucao-de-problemas/atendimentos) | | `does not allow changing tag_id or patient_id after creation` | [Atendimentos e agendamento](/guia/solucao-de-problemas/atendimentos) | | `… not found` em `Coverage.class.value` | [Cobertura, grupos e status](/guia/solucao-de-problemas/cobertura-e-grupos) | | `Group cannot be defined both in extension and contained` | [Cobertura, grupos e status](/guia/solucao-de-problemas/cobertura-e-grupos) | | `Select a valid choice` numa referência de campanha | [Configuração e ambientes](/guia/solucao-de-problemas/configuracao) | | `string contains invalid characters` | [Configuração e ambientes](/guia/solucao-de-problemas/configuracao) | | `401 Unauthorized` | [Configuração e ambientes](/guia/solucao-de-problemas/configuracao) | ## Quando abrir um chamado Alguns problemas não se resolvem do lado do integrador, e vale saber quais desde o começo: * **Configuração de `system` de identificador de paciente e de profissional** — só esses dois recursos casam por uma lista configurada, e ela é definida pela Nilo, por ambiente. Para os demais recursos você escolhe o `system` e usa, sem configuração nenhuma. * **Registros duplicados na base da Nilo** — quando dois registros do mesmo paciente ou do mesmo profissional já existem, nenhum payload seu resolve; a unificação é feita pela Nilo. * **Ids internos que você precisa referenciar** — o id de um plano de saúde, de um grupo, de um status ou de uma campanha vem da plataforma. Alguns são consultáveis pela API, outros não. * **Cadastros que faltam no ambiente de teste** — se o plano, a diretriz ou a campanha que você quer testar não existe em homologação, ela precisa ser cadastrada antes do teste. Ao abrir o chamado, mande o **payload enviado**, a **resposta recebida** com o `OperationOutcome` inteiro, o **ambiente** e o **horário aproximado** do envio. Sem o payload, quase toda investigação começa perguntando por ele.