Error reference - Pactmark

Compatibility: Pactmark 0.1.x. Codes are stable API. English messages are diagnostics and may change at any time.

The rule

// Wrong
if (error.message.includes("policy")) { /* … */ }

// Right
if (error.code === "KAF_POLICY_DENIED") { /* … */ }

Every failure carries a KAF_* code. Branch on the code, and on the code alone.

Serialization and schema

Code	Retryable	HTTP	Meaning
`KAF_SCHEMA_INVALID`	no	400	The value does not match the required schema
`KAF_SERIALIZATION_INVALID_JSON`	no	400	The JSON representation is invalid
`KAF_SERIALIZATION_DUPLICATE_KEY`	no	400	The JSON representation contains a duplicate key
`KAF_SERIALIZATION_INVALID_UNICODE`	no	400	The value contains invalid Unicode
`KAF_SERIALIZATION_NON_I_JSON_NUMBER`	no	400	The value contains a non-I-JSON number
`KAF_SERIALIZATION_UNSUPPORTED_VALUE`	no	400	The value cannot be represented as canonical JSON
`KAF_SERIALIZATION_CYCLIC_VALUE`	no	400	The value contains a cycle

Runtime and transitions

Code	Retryable	HTTP	Meaning
`KAF_RUNTIME_INVALID_TRANSITION`	no	409	The run event is not valid in the current state
`KAF_RUNTIME_TERMINAL`	no	409	The run is already terminal
`KAF_RUNTIME_EVENT_SEQUENCE`	yes	409	The event sequence conflicts with stored state
`KAF_RUNTIME_EVENT_BINDING`	no	409	The event does not belong to this run definition
`KAF_RUNTIME_AGENT_DEFINITION_MISMATCH`	no	409	The registered agent definition does not match the accepted run
`KAF_RUNTIME_CAPABILITY_MISSING`	no	503	A required runtime capability is unavailable
`KAF_RUNTIME_NOT_READY`	no	503	The runtime is not ready for the requested profile

KAF_RUNTIME_EVENT_SEQUENCE is retryable because it means another writer got there first — re-read and retry is the correct response. KAF_RUNTIME_TERMINAL is not, because no amount of retrying will un-terminate a run.

Authority and policy

Code	Retryable	HTTP	Meaning
`KAF_AUTHORIZATION_BINDING_MISMATCH`	no	403	The authorisation does not match the requested operation
`KAF_AUTHORIZATION_EXPIRED`	no	403	The authorisation has expired
`KAF_POLICY_DENIED`	no	403	Policy denied the operation
`KAF_ADMISSION_DENIED`	yes	429	The configured admission or quota limit was reached

Effects

Code	Retryable	HTTP	Meaning
`KAF_EFFECT_INVALID_TRANSITION`	no	409	The effect event is not valid in the current state
`KAF_EFFECT_ABANDONED_UNCERTAIN`	no	409	The uncertain effect was abandoned and may have occurred

KAF_EFFECT_ABANDONED_UNCERTAIN is not “it failed”. It is “we do not know, and we stopped waiting”. Treat anything downstream of it as unresolved until a human establishes the truth.

Storage

Code	Retryable	HTTP	Meaning
`KAF_STORAGE_CONCURRENCY_CONFLICT`	yes	409	Stored state changed concurrently
`KAF_STORAGE_NOT_FOUND`	no	404	The requested resource was not found
`KAF_STORAGE_SECURITY_PROFILE`	no	503	The storage security profile cannot accept this operation

KAF_STORAGE_NOT_FOUND is deliberately the same answer for “does not exist” and “exists but is not yours”. Denial must not become an enumeration oracle.

Model boundary

Code	Retryable	HTTP	Meaning
`KAF_MODEL_RESOURCE_LIMIT_EXCEEDED`	no	422	The model call exceeded its registered resource profile
`KAF_MODEL_CREDENTIAL_REQUIRED`	no	503	The model credential boundary is unavailable
`KAF_MODEL_ADAPTER_MISMATCH`	no	409	The model adapter does not match the registered model profile

Verification, evidence and patterns

Code	Retryable	HTTP	Meaning
`KAF_VERIFICATION_REQUIRED`	no	409	Required verification has not passed
`KAF_EVIDENCE_INVALID_REFERENCE`	no	409	Evidence refers to a missing or incompatible record
`KAF_PATTERN_INSUFFICIENT_EVIDENCE`	no	409	The evidence does not support the requested pattern maturity

Commands and idempotency

Code	Retryable	HTTP	Meaning
`KAF_COMMAND_IDEMPOTENCY_EXPIRED`	no	409	The command idempotency horizon has elapsed
`KAF_HTTP_IDEMPOTENCY_CONFLICT`	no	409	The idempotency key was already used for different content

Retrying correctly

Retry only when the typed classification and the effect strategy permit it. A timeout or a lost transport does not imply that an external effect did not occur — that is precisely the case the effect ledger exists to handle.

Of the whole registry, exactly three codes are marked retryable: KAF_RUNTIME_EVENT_SEQUENCE, KAF_ADMISSION_DENIED and KAF_STORAGE_CONCURRENCY_CONFLICT. All three are contention or quota conditions where the same request can safely be made again.

Wire format

{
  "type": "https://pactmark.dev/errors/policy-denied",
  "title": "KAF_POLICY_DENIED",
  "status": 403,
  "code": "KAF_POLICY_DENIED",
  "detail": "Policy denied the operation."
}

Problem Details, with the code duplicated where a client will actually look for it. Response bodies and logs use different disclosure levels — a response deliberately reveals less.

Run events

RunFailed.errorCode uses this registry.

HTTP API

Where each status appears on the wire.

​The rule

​Serialization and schema

​Runtime and transitions

​Authority and policy

​Effects

​Storage

​Model boundary

​Verification, evidence and patterns

​Commands and idempotency

​Retrying correctly

​Wire format

Run events

HTTP API

The rule

Serialization and schema

Runtime and transitions

Authority and policy

Effects

Storage

Model boundary

Verification, evidence and patterns

Commands and idempotency

Retrying correctly

Wire format