Ordem de envio e processamento
Um payload correto ainda pode falhar pelo jeito como foi enviado: um recurso antes da sua dependência, dois envios simultâneos do mesmo registro, ou um lote no endpoint errado. Esta página cobre esses casos.
Wrong ResourceType: … expects … but got Bundle
Causa. Um Bundle foi enviado para o endpoint de um recurso específico. Cada endpoint de
recurso aceita só aquele tipo.
O que fazer. Envie lotes para POST /fhir/resources/Bundle. Veja
Carga em lote.
As referências internas do lote não resolvem
Causa. O fullUrl das entradas não está no formato urn:uuid:…. Sem esse prefixo, a
referência de uma entrada para outra não é reconhecida como interna ao lote, e a Nilo passa a
procurar um recurso já cadastrado com aquele identificador — que não existe.
O que fazer. Use urn:uuid: no fullUrl de cada entrada e o mesmo valor no campo de
referência que aponta para ela. Veja
Referências entre entradas do mesmo lote.
”Recurso não encontrado” mesmo tendo enviado o recurso pai antes
Causa. O recurso pai e o dependente foram enviados em requisições separadas. Cada
requisição entra numa fila própria, e não há garantia de que a primeira termine antes da
segunda começar — mesmo que ela tenha sido aceita com 200 antes.
O que fazer. Recursos com dependência entre si vão no mesmo lote transacional, com referência interna. É o lote que garante a ordem e resolve as referências; requisições independentes não garantem nada disso. Esse é o caso de cobertura, atendimento, evento ou condição enviados junto com o paciente.
O contrário também é verdade: se os recursos não dependem um do outro, requisições separadas são mais simples e falham de forma mais isolada. O lote transacional é para dependência, não para volume.
Resource dependencies not processed successfully e Dependency … not processed successfully
Causa. Uma entrada do lote depende de outra que falhou. O recurso que você estava acompanhando não foi recusado por si — ele nem chegou a ser processado.
O que fazer. A mensagem traz o fullUrl da entrada que efetivamente falhou. Vá nela: o erro
real está na resposta dessa entrada, não na que você estava olhando. Corrigida a dependência,
reenvie o lote inteiro.
400 num envio simultâneo, sem erro de conteúdo aparente
Causa. Dois envios que tocam o mesmo registro ao mesmo tempo. Para não deixar um sobrescrever o outro pela metade, a escrita é serializada por recurso — e quando a espera estoura, a requisição perdedora volta com erro, embora o payload esteja correto.
O que fazer. Não envie em paralelo dois lotes que tocam o mesmo paciente. Serialize por paciente na origem e reenvie o que falhou: como a escrita é upsert, o reenvio é seguro.
429 Too Many Requests
Causa. Limite de escrita por tipo de recurso. Ele existe para proteger a plataforma de
rajadas — e uma rajada de redisparos automáticos em cima de um 429 só piora o quadro.
O que fazer. Trate 429 como “tente de novo mais tarde”, com espera crescente entre as
tentativas. Se o volume que você precisa enviar não caber no limite, o limite pode ser revisto —
abra um chamado com o volume esperado em vez de reduzir o intervalo entre as tentativas.
Quantos recursos cabem num lote
A recomendação é no máximo 10 entradas por lote, de preferência cinco — e ela não é validada pela API, que aceita mais. Lotes grandes degradam o processamento e, como não há rollback, um lote grande que falha no meio é mais difícil de reconciliar do que cinco chamadas avulsas.
Prefira agrupar por unidade de sentido — um paciente com suas coberturas e eventos — em vez de encher o lote. Veja Como montar.
value is not a valid list
Causa. Um campo que o FHIR define como lista foi enviado como objeto único, ou o contrário.
O caso mais comum é identifier enviado como objeto — ele é sempre uma lista. Também aparece em
campos que são lista de referências.
O que fazer. Confira a cardinalidade do campo na tabela de campos da página do recurso, ou na aba Referência. O erro nomeia o campo, e é literal quanto ao tipo esperado.
Aceito com 200, mas não aparece na tela
Causa. Três tempos diferentes se somam entre a resposta e a tela:
O que fazer. Confirme por um GET que o recurso está gravado — se estiver, a escrita está
correta e o resto é tempo. Reenviar não acelera nada e, se o reenvio for concorrente com o
processamento do primeiro, pode gerar um erro que não existiria. Atribuição de diretriz é o caso
mais visível disso: veja Plano de cuidado e diretriz.
500 ou timeout intermitente
Causa. Uma falha transitória no caminho entre os serviços internos. Ela é do lado da Nilo, e não indica nada de errado no payload.
O que fazer. Retente o mesmo payload. Como a escrita é upsert por identificador, o reenvio não duplica nada — desde que não seja simultâneo à tentativa anterior. Se o mesmo recurso falhar de forma consistente, abra um chamado com o payload e o horário.