diff --git a/docs/protocol-error-status-model.md b/docs/protocol-error-status-model.md index b51d029..995d9ed 100644 --- a/docs/protocol-error-status-model.md +++ b/docs/protocol-error-status-model.md @@ -46,6 +46,23 @@ Fields: - `at` (required, RFC3339 timestamp) - `details` (optional key-value map) +### Standard Error Codes + +The `code` field is a stable, machine-readable identifier. The following codes are defined by the protocol: + +| Code | Category | Retryable | Description | +|---|---|---|---| +| `agent_not_found` | `transport` | No | The target agent does not exist in the registry. | +| `invalid_agent_address` | `validation` | No | The agent address is syntactically invalid or does not conform to the expected format. | +| `schema_invalid` | `validation` | No | The intent payload does not conform to the expected schema. | +| `auth_failed` | `auth` | No | Authentication or authorization failed. | +| `policy_denied` | `policy` | No | The request was rejected by a policy rule. | +| `delivery_failed` | `transport` | Yes | The intent could not be delivered to the target agent. | +| `intent_timeout` | `timeout` | Yes | The intent exceeded its deadline without completion. | +| `internal_error` | `internal` | Yes | An unexpected internal error occurred. | + +Implementations may define additional codes within the `^[a-z0-9_:.\-]{3,128}$` pattern. Standard codes should be used where applicable for cross-implementation interoperability. + Usage: - Used for predictable API and workflow error payloads. diff --git a/schemas/protocol/intent.error.v1.json b/schemas/protocol/intent.error.v1.json index 3f4e84b..147dbd3 100644 --- a/schemas/protocol/intent.error.v1.json +++ b/schemas/protocol/intent.error.v1.json @@ -14,7 +14,17 @@ "properties": { "code": { "type": "string", - "pattern": "^[a-z0-9_:.\\-]{3,128}$" + "pattern": "^[a-z0-9_:.\\-]{3,128}$", + "examples": [ + "agent_not_found", + "invalid_agent_address", + "schema_invalid", + "auth_failed", + "policy_denied", + "delivery_failed", + "intent_timeout", + "internal_error" + ] }, "message": { "type": "string",