{"name":"KYA Pre-Dispute Network reason codes","version":"0.9","status":"Draft for comment","published":"2026-10-01","url":"https://knowyouragent.xyz/pre-dispute-network/reason-codes","usage":{"reason_codes":[{"method":"POST","path":"/api/v1/pre-dispute/alerts","field":"reason_code"}],"alert_types":[{"method":"POST","path":"/api/v1/pre-dispute/alerts","field":"alert_type"}],"requested_actions":[{"method":"POST","path":"/api/v1/pre-dispute/alerts","field":"requested_remedy.action"},{"method":"POST","path":"/api/v1/pre-dispute/alerts/{alert_id}/respond","field":"action_taken"}],"response_types":[{"method":"POST","path":"/api/v1/pre-dispute/alerts/{alert_id}/respond","field":"response_type"}],"relationship_statuses":[{"method":"POST","path":"/api/v1/pre-dispute/alerts/{alert_id}/respond","field":"relationship_status"}],"resolution_statuses":[{"method":"GET","path":"/api/v1/pre-dispute/alerts","field":"status"}]},"reason_codes":[{"code":"HALLUCINATION_LOOP","name":"Agent stuck in a loop","meaning":"The agent repeats unintended behavior, such as reordering or retrying, without new instruction.","example":"An agent retries a booking every few minutes after a timeout and creates several orders."},{"code":"SCOPE_EXCEEDED","name":"Outside the trace scope","meaning":"The action falls outside the scope the operator issued in the signed trace.","example":"A trace scoped to browsing and quotes is used to place an order."},{"code":"UNAUTHORIZED_ACCESS","name":"Unauthorized access","meaning":"The agent reached resources or account areas outside its authorization.","example":"An agent opens a merchant account page that its trace does not cover."},{"code":"AMOUNT_EXCEEDED","name":"Over the amount limit","meaning":"The transaction amount is above the trace cap or the delegated wallet limit.","example":"The trace caps the order at $149 and the cart comes to $188."},{"code":"WRONG_ITEM","name":"Wrong item","meaning":"The agent bought something other than what the principal asked for.","example":"The buyer asked for a size M jacket and the agent ordered size XL."},{"code":"DUPLICATE_ACTION","name":"Duplicate action","meaning":"The same intent produced repeated, unintended actions.","example":"One instruction to buy a gift produces two identical orders."},{"code":"REVOKED_DURING","name":"Revoked mid-transaction","meaning":"Authorization was revoked while the transaction was in progress.","example":"The operator revokes the trace while the agent is completing checkout."},{"code":"PRINCIPAL_DENIAL","name":"Principal denial","meaning":"The principal, usually the buyer, denies authorizing the agent’s action.","example":"The buyer tells the merchant they never asked their agent to make the purchase."},{"code":"OPERATOR_INITIATED","name":"Operator self-report","meaning":"The operator reports a problem with its own agent before anyone else raises it.","example":"An operator finds a pricing bug in its agent and reports the affected orders."},{"code":"SYSTEM_DETECTED","name":"System detected","meaning":"Automated monitoring flagged the action for review.","example":"An anomaly check flags an unusual burst of orders from one agent."}],"alert_types":[{"code":"pre_dispute_stop_loss","name":"Stop-loss alert","meaning":"Requests an immediate halt.","severity":"critical","response_window":"2 hours"},{"code":"pre_dispute_review","name":"Review alert","meaning":"Flags the case for review.","severity":"warning","response_window":"24 hours"},{"code":"pre_dispute_intent_query","name":"Intent query","meaning":"Asks what the agent was meant to do.","severity":"info","response_window":"No deadline"}],"response_types":[{"code":"ACCEPTED","name":"Accepted","meaning":"The responder accepts the issue and agrees to a remedy."},{"code":"COUNTER_OFFER","name":"Counter-offer","meaning":"The responder proposes a different resolution."},{"code":"DECLINED","name":"Declined","meaning":"The responder disputes the claim."},{"code":"NEEDS_INFO","name":"Needs information","meaning":"The responder asks for more context."},{"code":"AUTO_RESOLVED","name":"Auto-resolved","meaning":"A merchant automation rule resolved the alert."}],"requested_actions":[{"code":"VOID","name":"Void","meaning":"Cancel the transaction before settlement."},{"code":"REFUND","name":"Refund","meaning":"Return the full amount."},{"code":"PARTIAL_REFUND","name":"Partial refund","meaning":"Return part of the amount."},{"code":"VOID_AND_REFUND","name":"Void and refund","meaning":"Cancel what can be cancelled and refund the rest."},{"code":"REVIEW","name":"Review","meaning":"Hold the case for review before any money moves."},{"code":"ACKNOWLEDGE","name":"Acknowledge","meaning":"Record the issue without a monetary remedy."}],"relationship_statuses":[{"code":"MAINTAINED","name":"Maintained","meaning":"The merchant–operator relationship continues as before."},{"code":"WARNING_ISSUED","name":"Warning issued","meaning":"A warning is recorded on the relationship."},{"code":"PROBATION","name":"Probation","meaning":"The relationship continues under closer review."},{"code":"SUSPENDED","name":"Suspended","meaning":"Transactions between the merchant and the operator are paused."},{"code":"TERMINATED","name":"Terminated","meaning":"The relationship ends."}],"resolution_statuses":[{"code":"pending","name":"Pending","meaning":"Waiting for a response."},{"code":"resolved","name":"Resolved","meaning":"Closed after a response."},{"code":"auto_resolved","name":"Auto-resolved","meaning":"Closed by a merchant automation rule."},{"code":"escalated","name":"Escalated","meaning":"Moved outside the side-channel, for example to a chargeback."},{"code":"expired","name":"Expired","meaning":"The response deadline passed without a resolution."}]}