HALLUCINATION_LOOP
Agent stuck in a loop
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.
/ KYA PRE-DISPUTE NETWORKReason codes v0.9 · Draft for comment
KYA Pre-Dispute Network reason codes.
A shared vocabulary for problems with AI agent orders: 10 reason codes, 3 alert types, 5 response types, and the statuses a case moves through. Each list names the API field that uses it. Merchants and operators can use them to write rules and reports that line up.
VERSION 0.9PUBLISHED 2026-10-01
/ 01Reason codes
Why the alert was raised.
Each alert carries exactly one reason code. The examples illustrate the code; they are not records of real cases.
Used as reason_code on POST /api/v1/pre-dispute/alerts
SCOPE_EXCEEDED
Outside the trace scope
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.
UNAUTHORIZED_ACCESS
Unauthorized access
The agent reached resources or account areas outside its authorization.
Example: An agent opens a merchant account page that its trace does not cover.
AMOUNT_EXCEEDED
Over the amount limit
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.
WRONG_ITEM
Wrong item
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.
DUPLICATE_ACTION
Duplicate action
The same intent produced repeated, unintended actions.
Example: One instruction to buy a gift produces two identical orders.
REVOKED_DURING
Revoked mid-transaction
Authorization was revoked while the transaction was in progress.
Example: The operator revokes the trace while the agent is completing checkout.
PRINCIPAL_DENIAL
Principal denial
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.
OPERATOR_INITIATED
Operator self-report
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.
SYSTEM_DETECTED
System detected
Automated monitoring flagged the action for review.
Example: An anomaly check flags an unusual burst of orders from one agent.
/ 02Alert types
How urgent it is.
The alert type sets the severity and the response deadline recorded on the alert.
Used as alert_type on POST /api/v1/pre-dispute/alerts
- pre_dispute_stop_loss
- Stop-loss alert · critical
- 2 hours
- Requests an immediate halt.
- pre_dispute_review
- Review alert · warning
- 24 hours
- Flags the case for review.
- pre_dispute_intent_query
- Intent query · info
- No deadline
- Asks what the agent was meant to do.
/ 03Response types
How the other side answered.
Either the merchant or the operator can respond, depending on who opened the alert.
Used as response_type on POST /api/v1/pre-dispute/alerts/{alert_id}/respond
- ACCEPTED
- Accepted
- The responder accepts the issue and agrees to a remedy.
- COUNTER_OFFER
- Counter-offer
- The responder proposes a different resolution.
- DECLINED
- Declined
- The responder disputes the claim.
- NEEDS_INFO
- Needs information
- The responder asks for more context.
- AUTO_RESOLVED
- Auto-resolved
- A merchant automation rule resolved the alert.
/ 04Requested actions
What remedy was asked for or taken.
The party opening the alert can request a remedy, and the response records the action taken.
Used as requested_remedy.action on POST /api/v1/pre-dispute/alerts · action_taken on POST /api/v1/pre-dispute/alerts/{alert_id}/respond
- VOID
- Void
- Cancel the transaction before settlement.
- REFUND
- Refund
- Return the full amount.
- PARTIAL_REFUND
- Partial refund
- Return part of the amount.
- VOID_AND_REFUND
- Void and refund
- Cancel what can be cancelled and refund the rest.
- REVIEW
- Review
- Hold the case for review before any money moves.
- ACKNOWLEDGE
- Acknowledge
- Record the issue without a monetary remedy.
/ 05Relationship statuses
Where the merchant and operator stand afterward.
A response can record the state of the merchant–operator relationship after the case.
Used as relationship_status on POST /api/v1/pre-dispute/alerts/{alert_id}/respond
- MAINTAINED
- Maintained
- The merchant–operator relationship continues as before.
- WARNING_ISSUED
- Warning issued
- A warning is recorded on the relationship.
- PROBATION
- Probation
- The relationship continues under closer review.
- SUSPENDED
- Suspended
- Transactions between the merchant and the operator are paused.
- TERMINATED
- Terminated
- The relationship ends.
/ 06Resolution statuses
Where the case ended up.
Every alert is in exactly one resolution status. KYA sets it; clients read it and can filter alert listings by it.
Used as status on GET /api/v1/pre-dispute/alerts
- pending
- Pending
- Waiting for a response.
- resolved
- Resolved
- Closed after a response.
- auto_resolved
- Auto-resolved
- Closed by a merchant automation rule.
- escalated
- Escalated
- Moved outside the side-channel, for example to a chargeback.
- expired
- Expired
- The response deadline passed without a resolution.
/ 07Versioning
A draft, open for comment.
Version 0.9 matches the current alert API. Before 1.0, codes may be added, renamed, or split based on comments, and every change gets a new version number. The JSON file always reflects the version on this page.
Next step
Use these codes on your own agent orders.
We’ll set up the KYA Pre-Dispute Network on your checkout and map your existing dispute policy to these codes.