application/problem+json, con un code estable. Los códigos son SF- y cuatro dígitos. Cita el código cuando reportes un problema. La descripción general de la API describe el envelope y las convenciones que comparten todas las operaciones.
Códigos que responde el servicio
Los miembros
detail y errors[] nombran lo que falló. Léelos antes de actuar según la fila de abajo.
| Código | Estado HTTP | Cuándo responde el servicio | Qué hacer | Reintento |
|---|---|---|---|---|
| SF-0001 | 422 | No hay ninguna versión de contrato registrada para el producer, el namespace, el tipo de hecho y la versión de schema que nombra la solicitud (una versión obsoleta responde SF-0019). | Registra la versión del contrato desde tu pipeline de despliegue, antes del rollout del producer, y envía la solicitud de nuevo. | Después de corregir |
| SF-0002 | 409 | Ya existe una versión de contrato con la misma identidad y con contenido distinto. | Las versiones publicadas son inmutables: sube la versión del schema y usa las diferencias de errors[] para elegir el incremento. | No |
| SF-0003 | 409 | La nueva versión minor o patch no es compatible con las versiones ya registradas para el tipo de hecho. | Corrige el schema para que siga siendo compatible, o registra el cambio como una nueva versión major. | No |
| SF-0004 | 422 | El schema del contrato no es un JSON Schema válido y autocontenido, o una referencia declarada pide una correlación que su tipo de referencia no permite. | Dale al schema un $id absoluto, mantén todo $ref dentro del documento (#/$defs) y corrige los miembros de errors[]. | No |
| SF-0005 | 403 | El namespace está asignado a otro servicio producer, o el hecho se envía para un producer y un namespace que tu servicio no registró. | Registra y envía solo bajo un namespace que tu servicio posee, con la credencial de servicio del producer dueño. | No |
| SF-0006 | 422 | El envelope del hecho o la consulta está mal formado: falta un miembro, tiene un formato incorrecto o no forma parte del envelope, o el período de un listado está vacío. | Corrige los miembros de errors[] y envía la solicitud de nuevo. | No |
| SF-0007 | 422 | El payload del hecho (data) no valida contra el JSON Schema del contrato registrado. | Corrige los campos del payload de errors[] para que coincidan con el contrato. | No |
| SF-0008 | 422 | El hecho trae una referencia que el contrato no declara, una clave de ámbito que su tipo de referencia no declara, o más de cinco referencias distintas de correlación exacta. | Envía solo las referencias y las claves de ámbito que declaran el contrato y sus tipos de referencia. | No |
| SF-0009 | 404 | No existe ningún flujo con el identificador dado. | Verifica el identificador: un identificador absorbido por un merge sigue resolviendo, uno desconocido no. | No |
| SF-0010 | 404 | Ningún flujo trae una referencia con el tipo, el valor y el ámbito dados. | Verifica el tipo de referencia, el valor y cada clave de ámbito de la consulta. | No |
| SF-0011 | 409 | Más de un flujo trae la referencia, así que la búsqueda no puede elegir uno. | Elige un flujo de candidates[] y léelo por su flowAggregationId. | No |
| SF-0012 | 413 | El cuerpo de la solicitud supera el límite de tamaño configurado (256 KiB por defecto para un envelope de hecho). | Reduce el cuerpo de la solicitud. Para un hecho, envía una declaración sobre una ocurrencia, no un documento. | No |
| SF-0013 | 401 | La solicitud no trae un bearer token válido. | Envía un bearer token válido emitido para el tenant. Un producer usa su credencial de servicio. | Después de corregir |
| SF-0014 | 403 | El token es válido, pero le falta un permiso que exige la operación, como catalog:reserved, que todo registro de catálogo necesita porque todo nombre de catálogo está bajo un prefijo reservado. | Pide al administrador del tenant que otorgue el permiso que lista la operación y envía la solicitud de nuevo. | Después de corregir |
| SF-0015 | 500 | El servicio falló por un motivo que la solicitud no causó. | Reintenta más tarde con la misma solicitud. Las escrituras son idempotentes, así que reintentar es seguro. | Sí, más tarde |
| SF-0016 | 409 | Ya hay almacenado un hecho con el mismo factId y con contenido distinto. | Los hechos son inmutables: envía una ocurrencia modificada como un hecho nuevo con un factId nuevo y revisa el producer que reusó el identificador. | No |
| SF-0017 | 404 | El catálogo no tiene ninguna versión de contrato con el producer, el namespace, el tipo de hecho y la versión de schema dados. | Verifica los cuatro segmentos de la ruta y, si falta la versión, regístrala desde tu pipeline de despliegue. | No |
| SF-0018 | 422 | El hash de contenido enviado con el contrato no coincide con el contenido que acompaña. | Recalcula el hash de contenido sobre el mismo contenido que envías. | No |
| SF-0019 | 422 | La versión del contrato está obsoleta y ya no acepta hechos. | Envía el hecho contra una versión activa del mismo tipo de hecho. | No |
| SF-0020 | 403 | Un operador desactivó la emisión de hechos para este tenant. | Mantén el hecho pendiente y reintenta más tarde. Los hechos se aceptan de nuevo cuando un operador activa la emisión. | Sí, más tarde |
| SF-0021 | 422 | El contrato declara un tipo de referencia que el catálogo de tipos de referencia no tiene. errors[] lista cada tipo que falta. | Pide al dueño que registre cada tipo de referencia antes de que registres el contrato que lo usa. | Después de corregir |
| SF-0022 | 409 | Ya existe un tipo de referencia con el mismo nombre y con otra definición. | Los tipos de referencia son inmutables: usa un nombre de tipo nuevo para un significado nuevo. | No |
| SF-0023 | 422 | El nombre del namespace o del tipo de referencia no empieza con ninguno de los prefijos reservados del despliegue. | Usa un nombre cuyo primer segmento separado por punto sea un prefijo reservado del despliegue. | No |
| SF-0024 | 422 | Los flujos se listan por un tipo de referencia que no está registrado o que se registró con searchable: false. | Lista flujos solo por un tipo de referencia registrado con searchable: true, o lee el único flujo de una referencia exacta con findFlowByReference. | No |
| SF-0025 | 422 | Una anotación x-sensitivity o x-mask del schema del contrato está mal ubicada o trae un valor desconocido. | Declara x-sensitivity (masked, hashed o encrypted) solo en una propiedad string alcanzada por properties, y x-mask solo junto a masked o encrypted. | No |
| SF-0026 | 422 | La versión del contrato que nombra el hecho trae anotaciones de sensibilidad mal formadas, así que su payload no se puede proteger y no se almacena nada. | Registra una versión corregida del contrato y envía el hecho contra ella. | Después de corregir |
| SF-0027 | 403 | En modo multi-tenant, la credencial no nombra un servicio producer, así que no se puede decidir quién es dueño del namespace. | Usa la credencial de servicio del producer para el tenant y rota una credencial emitida antes de que trajera el nombre del producer. | Después de corregir |
| SF-0028 | 403 | En modo multi-tenant, la credencial de servicio del producer se creó sin nombrar su servicio producer. | Pide al administrador del tenant que vuelva a crear la credencial con su servicio producer definido. Rotar la misma credencial no lo resuelve. | Después de corregir |
| SF-0090 | 400 | La solicitud está mal formada, por ejemplo un cuerpo que no es JSON válido. | Corrige la sintaxis de la solicitud y envíala de nuevo. | No |
| SF-0091 | 404 | El recurso pedido no existe, por ejemplo un tipo de referencia o una ruta desconocidos. | Verifica la ruta y el nombre del recurso. Un tipo de referencia existe solo después de que su dueño lo registra. | No |
| SF-0092 | 422 | La solicitud no coincide con el schema de solicitud de la operación, por ejemplo un miembro inesperado o un cursor inválido. | Corrige los miembros de errors[] para que la solicitud coincida con el schema de la operación. | No |
| SF-0093 | 409 | La solicitud entra en conflicto con el estado actual de un recurso. | Lee el recurso de nuevo y envía una solicitud coherente con su estado actual. | No |
| SF-0094 | 503 | El servicio no puede responder ahora: está arrancando, el servicio de autorización no está disponible por un momento o las claves de correlación del hecho siguieron ocupadas. | Reintenta más tarde con la misma solicitud y respeta Retry-After cuando la respuesta lo traiga. | Sí, más tarde |
| SF-0095 | 429 | El llamador envió más solicitudes de las que permite el rate limit. | Espera el retraso de Retry-After antes de la siguiente solicitud. | Sí, más tarde |
| SF-0096 | 400 | La solicitud se rechazó por un motivo del lado del cliente que ningún código más específico describe. La respuesta conserva el estado HTTP de ese motivo, por ejemplo 405 o 415. | Lee el miembro detail, corrige la solicitud y envíala de nuevo. | No |