UAT: `errors.py` missing `DUPLICATE_ENTITY` (-32005) and `BUDGET_EXCEEDED` (-32006) A2A error code constants — documented in taxonomy but not defined #4866

New issue

Open

opened 2026-04-08 20:10:37 +00:00 by HAL9000 · 0 comments

HAL9000 commented

2026-04-08 20:10:37 +00:00

Owner

Bug Report

Tested by: UAT tester instance uat-tester-a2a-protocol
Feature area: A2A Protocol — JSON-RPC 2.0 error code taxonomy
Severity: Medium — error codes documented in the taxonomy comment are not defined as constants, causing inconsistent error handling

What Was Tested

Code-level analysis of src/cleveragents/a2a/errors.py — the error code constants vs the documented taxonomy.

Expected Behavior (from spec)

The errors.py file documents the following A2A error code taxonomy in its module-level comment:

# Application-defined codes (per docs/reference/a2a.md §Error Code Taxonomy):
#   -32001  Resource not found
#   -32002  Authentication required
#   -32003  Authorization forbidden
#   -32004  Invalid state / business rule violation
#   -32005  Duplicate entity          ← DOCUMENTED BUT NOT DEFINED
#   -32006  Budget exceeded            ← DOCUMENTED BUT NOT DEFINED
#   -32007  Version mismatch           ← DOCUMENTED BUT NOT DEFINED
#   -32008  Plan error
#   -32009  Configuration error

All 9 documented error codes should have corresponding Python constants.

Actual Behavior

Only 7 of the 9 documented error codes are defined as constants:

# Defined:
NOT_FOUND: int = -32001
AUTH_ERROR: int = -32002
FORBIDDEN: int = -32003
INVALID_STATE: int = -32004
# -32005 DUPLICATE_ENTITY ← MISSING
# -32006 BUDGET_EXCEEDED  ← MISSING
# -32007 VERSION_MISMATCH ← MISSING (though A2aVersionMismatchError exists)
PLAN_ERROR: int = -32008
CONFIGURATION_ERROR: int = -32009
VALIDATION_ERROR: int = -32602
INTERNAL_ERROR: int = -32603

The map_domain_error function also has no mapping for duplicate entity errors or budget exceeded errors, so these domain exceptions would fall through to the generic INTERNAL_ERROR code.

Code Location

src/cleveragents/a2a/errors.py — error code constants section (lines ~30–50)
src/cleveragents/a2a/errors.py — map_domain_error() function

Impact

Any domain exception representing a duplicate entity (e.g., DuplicateEntityError) or budget exceeded condition would be mapped to INTERNAL_ERROR (-32603) instead of the correct application-specific code. This makes it impossible for clients to distinguish these error types.

Expected Fix

Add the missing constants:

DUPLICATE_ENTITY: int = -32005
BUDGET_EXCEEDED: int = -32006
VERSION_MISMATCH: int = -32007

And update map_domain_error() to map the corresponding domain exceptions to these codes. Also add the new constants to __all__.

Automated by CleverAgents Bot
Supervisor: UAT Testing | Agent: uat-tester

## Bug Report **Tested by:** UAT tester instance `uat-tester-a2a-protocol` **Feature area:** A2A Protocol — JSON-RPC 2.0 error code taxonomy **Severity:** Medium — error codes documented in the taxonomy comment are not defined as constants, causing inconsistent error handling --- ### What Was Tested Code-level analysis of `src/cleveragents/a2a/errors.py` — the error code constants vs the documented taxonomy. ### Expected Behavior (from spec) The `errors.py` file documents the following A2A error code taxonomy in its module-level comment: ```python # Application-defined codes (per docs/reference/a2a.md §Error Code Taxonomy): # -32001 Resource not found # -32002 Authentication required # -32003 Authorization forbidden # -32004 Invalid state / business rule violation # -32005 Duplicate entity ← DOCUMENTED BUT NOT DEFINED # -32006 Budget exceeded ← DOCUMENTED BUT NOT DEFINED # -32007 Version mismatch ← DOCUMENTED BUT NOT DEFINED # -32008 Plan error # -32009 Configuration error ``` All 9 documented error codes should have corresponding Python constants. ### Actual Behavior Only 7 of the 9 documented error codes are defined as constants: ```python # Defined: NOT_FOUND: int = -32001 AUTH_ERROR: int = -32002 FORBIDDEN: int = -32003 INVALID_STATE: int = -32004 # -32005 DUPLICATE_ENTITY ← MISSING # -32006 BUDGET_EXCEEDED ← MISSING # -32007 VERSION_MISMATCH ← MISSING (though A2aVersionMismatchError exists) PLAN_ERROR: int = -32008 CONFIGURATION_ERROR: int = -32009 VALIDATION_ERROR: int = -32602 INTERNAL_ERROR: int = -32603 ``` The `map_domain_error` function also has no mapping for duplicate entity errors or budget exceeded errors, so these domain exceptions would fall through to the generic `INTERNAL_ERROR` code. ### Code Location - `src/cleveragents/a2a/errors.py` — error code constants section (lines ~30–50) - `src/cleveragents/a2a/errors.py` — `map_domain_error()` function ### Impact Any domain exception representing a duplicate entity (e.g., `DuplicateEntityError`) or budget exceeded condition would be mapped to `INTERNAL_ERROR (-32603)` instead of the correct application-specific code. This makes it impossible for clients to distinguish these error types. ### Expected Fix Add the missing constants: ```python DUPLICATE_ENTITY: int = -32005 BUDGET_EXCEEDED: int = -32006 VERSION_MISMATCH: int = -32007 ``` And update `map_domain_error()` to map the corresponding domain exceptions to these codes. Also add the new constants to `__all__`. --- **Automated by CleverAgents Bot** Supervisor: UAT Testing | Agent: uat-tester

HAL9000 referenced this issue

2026-04-08 20:12:12 +00:00

[Automated] CleverAgents Build Session - 2026-04-08 #4799

HAL9000 referenced this issue

2026-04-08 20:16:04 +00:00

[Automated] CleverAgents Build Session - 2026-04-08 #4799

HAL9000 added this to the v3.5.0 milestone

2026-04-08 20:16:28 +00:00

HAL9000 referenced this issue

2026-04-08 20:18:59 +00:00

[Automated] CleverAgents Build Session - 2026-04-08 #4799

HAL9000 referenced this issue