application/problem+json, with a stable code. Codes are SF- and four digits. Quote the code when you report a problem. The API overview describes the envelope and the conventions every operation shares.
Codes the service answers
The
detail and errors[] members name the specific thing that failed. Read them before you act on the row below.
| Code | HTTP status | When the service answers it | What to do | Retry |
|---|---|---|---|---|
| SF-0001 | 422 | No contract version is registered for the producer, namespace, fact type and schema version the request names (a deprecated version answers SF-0019). | Register the contract version from your deploy pipeline, before the producer rolls out, then send the request again. | After a fix |
| SF-0002 | 409 | A contract version with the same identity is already registered with different content. | Published versions are immutable: bump the schema version, using the differences listed in errors[] to choose the bump. | No |
| SF-0003 | 409 | The new minor or patch version is not compatible with the versions already registered for the fact type. | Fix the schema so it stays compatible, or register the change as a new major version. | No |
| SF-0004 | 422 | The contract schema is not a valid, self-contained JSON Schema, or a declared reference asks for a correlation its reference type does not allow. | Give the schema an absolute $id, keep every $ref inside the document (#/$defs), and fix the members listed in errors[]. | No |
| SF-0005 | 403 | The namespace is bound to another producer service, or the fact is sent for a producer and namespace your service did not register. | Register and send only under a namespace your service owns, with the service credential of the owning producer. | No |
| SF-0006 | 422 | The fact envelope or the query is malformed: a member is missing, has the wrong format or is not part of the envelope, or a listing period is empty. | Fix the members listed in errors[] and send the request again. | No |
| SF-0007 | 422 | The fact payload (data) does not validate against the JSON Schema of the registered contract. | Fix the payload fields listed in errors[] so they match the contract. | No |
| SF-0008 | 422 | The fact carries a reference the contract does not declare, a scope key its reference type does not declare, or more than five distinct exact-correlation references. | Send only the references and scope keys that the contract and its reference types declare. | No |
| SF-0009 | 404 | No flow exists with the given flow identifier. | Verify the identifier: an identifier absorbed by a merge still resolves, an unknown one does not. | No |
| SF-0010 | 404 | No flow carries a reference with the given type, value and scope. | Verify the reference type, the value and every scope key of the query. | No |
| SF-0011 | 409 | More than one flow carries the reference, so the lookup cannot choose one. | Pick a flow from candidates[] and read it by its flowAggregationId. | No |
| SF-0012 | 413 | The request body is larger than the configured size limit (256 KiB by default for a fact envelope). | Reduce the request body; for a fact, send a statement about an occurrence, not a document. | No |
| SF-0013 | 401 | The request carries no valid bearer token. | Send a valid bearer token issued for the tenant; a producer uses its service credential. | After a fix |
| SF-0014 | 403 | The token is valid but lacks a permission the operation requires, such as catalog:reserved, which every catalog registration needs because every catalog name sits under a reserved prefix. | Ask the tenant administrator to grant the permission the operation lists, then send the request again. | After a fix |
| SF-0015 | 500 | The service failed for a reason the request did not cause. | Retry later with the same request; writes are idempotent, so a retry is safe. | Yes, later |
| SF-0016 | 409 | A fact with the same factId is already stored with different content. | Facts are immutable: send a changed occurrence as a new fact with a new factId, and check the producer that reused the identifier. | No |
| SF-0017 | 404 | The catalog holds no contract version with the given producer, namespace, fact type and schema version. | Verify the four path segments, and register the version from your deploy pipeline if it is missing. | No |
| SF-0018 | 422 | The content hash sent with the contract does not match the content it accompanies. | Recompute the content hash over the same content you are sending. | No |
| SF-0019 | 422 | The contract version is deprecated and no longer accepts facts. | Send the fact against an active version of the same fact type. | No |
| SF-0020 | 403 | An operator has disabled fact emission for this tenant. | Keep the fact pending and retry later; facts are accepted again once an operator enables emission. | Yes, later |
| SF-0021 | 422 | The contract declares a reference type the reference-type catalog does not hold; errors[] lists every missing type. | Have the owner register each reference type before you register the contract that uses it. | After a fix |
| SF-0022 | 409 | A reference type with the same name is already registered with a different definition. | Reference types are immutable: use a new type name for a new meaning. | No |
| SF-0023 | 422 | The namespace or reference-type name does not start with one of the reserved prefixes of the deployment. | Use a name whose first dotted segment is a reserved prefix of the deployment. | No |
| SF-0024 | 422 | Flows are listed by a reference type that is not registered, or is registered with searchable: false. | List flows only by a reference type registered with searchable: true, or read the one flow of an exact reference with findFlowByReference. | No |
| SF-0025 | 422 | An x-sensitivity or x-mask annotation in the contract schema is misplaced or carries an unknown value. | Declare x-sensitivity (masked, hashed or encrypted) only on a string property reached through properties, and x-mask only next to masked or encrypted. | No |
| SF-0026 | 422 | The contract version the fact names carries malformed sensitivity annotations, so its payload cannot be protected and nothing is stored. | Register a corrected contract version and send the fact against it. | After a fix |
| SF-0027 | 403 | In multi-tenant mode, the credential does not name a producer service, so namespace ownership cannot be decided. | Use the service credential of the producer for the tenant, and rotate a credential issued before it carried the producer name. | After a fix |
| SF-0028 | 403 | In multi-tenant mode, the service credential of the producer was created without naming its producer service. | Ask the tenant administrator to recreate the credential with its producer service set; rotating the same credential does not fix this. | After a fix |
| SF-0090 | 400 | The request is malformed, such as a body that is not valid JSON. | Fix the request syntax and send it again. | No |
| SF-0091 | 404 | The requested resource does not exist, such as an unknown reference type or path. | Verify the path and the resource name; a reference type exists only after its owner registers it. | No |
| SF-0092 | 422 | The request does not match the request schema of the operation, such as an unexpected member or an invalid cursor. | Fix the members listed in errors[] so the request matches the schema of the operation. | No |
| SF-0093 | 409 | The request conflicts with the current state of a resource. | Read the resource again and send a request consistent with its current state. | No |
| SF-0094 | 503 | The service cannot answer right now: it is starting, the authorization service is temporarily unavailable, or the correlation keys of the fact stayed busy. | Retry later with the same request, honoring Retry-After when the response carries it. | Yes, later |
| SF-0095 | 429 | The caller sent more requests than the rate limit allows. | Wait for the Retry-After delay before the next request. | Yes, later |
| SF-0096 | 400 | The request was refused for a client-side reason no more specific code describes; the response keeps the HTTP status of that reason, such as 405 or 415. | Read the detail member, fix the request and send it again. | No |