Respuestas y errores

Respuesta exitosa

Si el envío se acepta, la API responde 202 Accepted. Significa recibido y encolado, no "ya procesado": el impacto en el sistema es asíncrono.

Errores de validación

Si el envío se rechaza, la API responde un OperationOutcome de FHIR con un código de error estable en issue.details.coding.code:

{
  "resourceType": "OperationOutcome",
  "issue": [
    {
      "severity": "error",
      "code": "not-found",
      "details": { "coding": [{ "code": "PATIENT_NOT_FOUND" }] },
      "diagnostics": "Encounter references patient \"PAC-99\" which does not exist"
    }
  ]
}

Código	HTTP	Significado
INVALID_BUNDLE	400	El body no es un Bundle/recurso FHIR válido
UNSUPPORTED_RESOURCE_TYPE	422	resourceType no soportado
MISSING_IDENTIFIER	422	Falta el identificador de la entidad
MISSING_REFERENCE	422	Falta una referencia obligatoria (p. ej. Encounter.subject)
PATIENT_NOT_FOUND	422	Se referencia un paciente que no existe
ENCOUNTER_NOT_FOUND	422	Se referencia un episodio que no existe
PROCEDURE_NOT_FOUND	422	Se referencia una práctica que no existe
TARGET_NOT_FOUND	422	DocumentReference.subject.type no es Patient/Encounter/Procedure

Errores de autenticación: 401 (API key faltante/incorrecta o IP no permitida).

Idempotencia

El header x-source-message-id identifica el envío. Si reenviás el mismo id, el envío se trata como duplicado: se responde 202 pero no se reprocesa. Usá un id nuevo por cada envío; reservá el reintento con el mismo id para reintentos ante fallas de red.

Orden y dependencias

El procesamiento tolera el desorden y reintenta, pero cada recurso necesita que su "padre" exista (en el mismo Bundle o enviado antes): una práctica necesita su episodio; un episodio, su paciente. Si preferís, mandá todo junto en un Bundle transaction.

El 202 no garantiza el impacto final

La validación referencial ocurre al recibir (y devuelve error en el momento). Otras reglas de negocio (p. ej. que el plan o el código de práctica existan en los catálogos acordados) se resuelven durante el procesamiento asíncrono. Asegurate de enviar valores de catálogo válidos, acordados en el onboarding.