Compare commits

...

6 Commits

Author SHA1 Message Date
Darrel Miller
3ea24d4906 docs: Update JSON-RPC binding to include google.rpc.ErrorInfo structure for A2A errors 2026-03-11 09:28:23 -04:00
Mike Smith
e49ff5ce5c
Lint fix 2026-03-06 23:36:15 +00:00
Mike Smith
d9475c457e
Add clarification that additional details are allowed. 2026-03-06 23:31:13 +00:00
Mike Smith
ca9b13effe
Apply suggestions from code review
Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>
2026-03-06 23:30:04 +00:00
Mike Smith
c0894bb8cc
Merge branch 'main' into error-updates 2026-03-06 23:27:18 +00:00
Mike Smith
4aaa185597
docs: Update HTTP+JSON error mapping to use google.rpc.Status
For alignment with gRPC transcoding.
2026-03-06 23:22:47 +00:00

View File

@ -1179,17 +1179,17 @@ When an agent supports multiple protocols, all supported protocols **MUST**:
All A2A-specific errors defined in [Section 3.3.2](#332-error-handling) **MUST** be mapped to binding-specific error representations. The following table provides the canonical mappings for each standard protocol binding:
| A2A Error Type | JSON-RPC Code | gRPC Status | HTTP Status | HTTP Type URI |
| :------------------------------------ | :------------ | :-------------------- | :--------------------------- | :------------------------------------------------------------------- |
| `TaskNotFoundError` | `-32001` | `NOT_FOUND` | `404 Not Found` | `https://a2a-protocol.org/errors/task-not-found` |
| `TaskNotCancelableError` | `-32002` | `FAILED_PRECONDITION` | `409 Conflict` | `https://a2a-protocol.org/errors/task-not-cancelable` |
| `PushNotificationNotSupportedError` | `-32003` | `UNIMPLEMENTED` | `400 Bad Request` | `https://a2a-protocol.org/errors/push-notification-not-supported` |
| `UnsupportedOperationError` | `-32004` | `UNIMPLEMENTED` | `400 Bad Request` | `https://a2a-protocol.org/errors/unsupported-operation` |
| `ContentTypeNotSupportedError` | `-32005` | `INVALID_ARGUMENT` | `415 Unsupported Media Type` | `https://a2a-protocol.org/errors/content-type-not-supported` |
| `InvalidAgentResponseError` | `-32006` | `INTERNAL` | `502 Bad Gateway` | `https://a2a-protocol.org/errors/invalid-agent-response` |
| `ExtendedAgentCardNotConfiguredError` | `-32007` | `FAILED_PRECONDITION` | `400 Bad Request` | `https://a2a-protocol.org/errors/extended-agent-card-not-configured` |
| `ExtensionSupportRequiredError` | `-32008` | `FAILED_PRECONDITION` | `400 Bad Request` | `https://a2a-protocol.org/errors/extension-support-required` |
| `VersionNotSupportedError` | `-32009` | `UNIMPLEMENTED` | `400 Bad Request` | `https://a2a-protocol.org/errors/version-not-supported` |
| A2A Error Type | JSON-RPC Code | gRPC Status | HTTP Status |
| :------------------------------------ | :------------ | :-------------------- | :--------------------------- |
| `TaskNotFoundError` | `-32001` | `NOT_FOUND` | `404 Not Found` |
| `TaskNotCancelableError` | `-32002` | `FAILED_PRECONDITION` | `409 Conflict` |
| `PushNotificationNotSupportedError` | `-32003` | `UNIMPLEMENTED` | `400 Bad Request` |
| `UnsupportedOperationError` | `-32004` | `UNIMPLEMENTED` | `400 Bad Request` |
| `ContentTypeNotSupportedError` | `-32005` | `INVALID_ARGUMENT` | `415 Unsupported Media Type` |
| `InvalidAgentResponseError` | `-32006` | `INTERNAL` | `502 Bad Gateway` |
| `ExtendedAgentCardNotConfiguredError` | `-32007` | `FAILED_PRECONDITION` | `400 Bad Request` |
| `ExtensionSupportRequiredError` | `-32008` | `FAILED_PRECONDITION` | `400 Bad Request` |
| `VersionNotSupportedError` | `-32009` | `UNIMPLEMENTED` | `400 Bad Request` |
**Custom Binding Requirements:**
@ -2373,7 +2373,7 @@ JSON-RPC error responses use the standard [JSON-RPC 2.0 error object](https://ww
- **Error Code**: Mapped to `error.code` (numeric JSON-RPC error code)
- **Error Message**: Mapped to `error.message` (human-readable string)
- **Error Details**: Mapped to `error.data` (optional structured object)
- **Error Details**: Mapped to `error.data` (array containing `google.protobuf.Any` messages, using ProtoJSON representation)
**Standard JSON-RPC Error Codes:**
@ -2389,6 +2389,17 @@ JSON-RPC error responses use the standard [JSON-RPC 2.0 error object](https://ww
A2A-specific errors use codes in the range `-32001` to `-32099`. For the complete mapping of A2A error types to JSON-RPC error codes, see [Section 5.4 (Error Code Mappings)](#54-error-code-mappings).
**A2A Error Representation:**
For A2A-specific errors, implementations **MUST** include a `google.rpc.ErrorInfo` message in the `data` array with:
- `@type`: Set to `"type.googleapis.com/google.rpc.ErrorInfo"`
- `reason`: The A2A error type in UPPER_SNAKE_CASE without the "Error" suffix (e.g., `TASK_NOT_FOUND`)
- `domain`: Set to `"a2a-protocol.org"`
- `metadata`: Optional map of additional error context
Additional error context **MAY** be included in the `data` array.
**Error Response Structure:**
```json
@ -2414,16 +2425,21 @@ A2A-specific errors use codes in the range `-32001` to `-32099`. For the complet
"error": {
"code": -32001,
"message": "Task not found",
"data": {
"taskId": "nonexistent-task-id",
"timestamp": "2025-11-09T10:30:00.000Z"
}
"data": [
{
"@type": "type.googleapis.com/google.rpc.ErrorInfo",
"reason": "TASK_NOT_FOUND",
"domain": "a2a-protocol.org",
"metadata": {
"taskId": "nonexistent-task-id",
"timestamp": "2025-11-09T10:30:00.000Z"
}
}
]
}
}
```
The `data` field **MAY** include additional context-specific information to help clients diagnose and resolve the error.
## 10. gRPC Protocol Binding
The gRPC Protocol Binding provides a high-performance, strongly-typed interface using Protocol Buffers over HTTP/2. The gRPC Protocol Binding leverages the [API guidelines](https://google.aip.dev/general) to simplify gRPC to HTTP mapping.
@ -2821,29 +2837,43 @@ All query parameter values **MUST** be properly URL-encoded per [RFC 3986](https
### 11.6. Error Handling
HTTP error responses use [RFC 9457 Problem Details](https://www.rfc-editor.org/rfc/rfc9457.html) format with `Content-Type: application/problem+json`, which maps to the generic A2A error model defined in [Section 3.3.2](#332-error-handling) as follows:
HTTP error responses use the ProtoJSON representation of the [`google.rpc.Status`](https://github.com/googleapis/googleapis/blob/master/google/rpc/status.proto) structure, which maps to the generic A2A error model defined in [Section 3.3.2](#332-error-handling) as follows:
- **Error Code**: Mapped to `status` (HTTP status code) and `type` (URI identifier)
- **Error Message**: Mapped to `detail` (human-readable string)
- **Error Details**: Mapped to extension fields in the problem details object
- **Error Code**: Mapped to the HTTP status code and the `code` field (gRPC status code integer)
- **Error Message**: Mapped to the `message` field (human-readable string)
- **Error Details**: Mapped to the `details` array (containing `google.protobuf.Any` messages)
**A2A Error Representation:**
For A2A-specific errors, the `type` field **MUST** use the URI from the mapping table in [Section 5.4 (Error Code Mappings)](#54-error-code-mappings). Additional error context **MAY** be included as extension fields in the problem details object.
For A2A-specific errors, implementations **MUST** include a `google.rpc.ErrorInfo` message in the `details` array with:
- `@type`: Set to `"type.googleapis.com/google.rpc.ErrorInfo"`
- `reason`: The A2A error type in UPPER_SNAKE_CASE without the "Error" suffix (e.g., `TASK_NOT_FOUND`)
- `domain`: Set to `"a2a-protocol.org"`
- `metadata`: Optional map of additional error context
For the complete mapping of A2A error types to HTTP and gRPC status codes, see [Section 5.4 (Error Code Mappings)](#54-error-code-mappings). Additional error context **MAY** be included in the `details` array of the Status object.
**Error Response Example:**
```http
HTTP/1.1 404 Not Found
Content-Type: application/problem+json
Content-Type: application/json
{
"type": "https://a2a-protocol.org/errors/task-not-found",
"title": "Task Not Found",
"status": 404,
"detail": "The specified task ID does not exist or is not accessible",
"taskId": "task-123",
"timestamp": "2025-11-09T10:30:00.000Z"
"code": 5,
"message": "The specified task ID does not exist or is not accessible",
"details": [
{
"@type": "type.googleapis.com/google.rpc.ErrorInfo",
"reason": "TASK_NOT_FOUND",
"domain": "a2a-protocol.org",
"metadata": {
"taskId": "task-123",
"timestamp": "2025-11-09T10:30:00.000Z"
}
}
]
}
```