test

Specification excerpt: refs/A2A/docs/specification.md, Section 3.3.2 Error Handling

All operations may return errors in the following categories. Servers MUST return appropriate errors and SHOULD provide actionable information to help clients resolve issues.

Error Categories and Server Requirements:

• Authentication Errors: Invalid or missing credentials

  • Servers MUST reject requests with invalid or missing authentication credentials
  • Servers SHOULD include authentication challenge information in the error response
  • Servers SHOULD specify which authentication scheme is required
  • Example error codes: HTTP 401 Unauthorized, gRPC UNAUTHENTICATED, JSON-RPC custom error
  • Example scenarios: Missing bearer token, expired API key, invalid OAuth token

• Authorization Errors: Insufficient permissions for requested operation

  • Servers MUST return an authorization error when the authenticated client lacks required permissions
  • Servers SHOULD indicate what permission or scope is missing (without leaking sensitive information about resources the client cannot access)
  • Servers MUST NOT reveal the existence of resources the client is not authorized to access
  • Example error codes: HTTP 403 Forbidden, gRPC PERMISSION_DENIED, JSON-RPC custom error
  • Example scenarios: Attempting to access a task created by another user, insufficient OAuth scopes

• Validation Errors: Invalid input parameters or message format

  • Servers MUST validate all input parameters before processing
  • Servers SHOULD specify which parameter(s) failed validation and why
  • Servers SHOULD provide guidance on valid parameter values or formats
  • Example error codes: HTTP 400 Bad Request, gRPC INVALID_ARGUMENT, JSON-RPC -32602 Invalid params
  • Example scenarios: Invalid task ID format, missing required message parts, unsupported content type

• Resource Errors: Requested task not found or not accessible

  • Servers MUST return a not found error when a requested resource does not exist or is not accessible to the authenticated client
  • Servers SHOULD NOT distinguish between "does not exist" and "not authorized" to prevent information leakage
  • Example error codes: HTTP 404 Not Found, gRPC NOT_FOUND, JSON-RPC custom error (see A2A-specific errors)
  • Example scenarios: Task ID does not exist, task has been deleted, configuration not found

• System Errors: Internal agent failures or temporary unavailability

  • Servers SHOULD return appropriate error codes for temporary failures vs. permanent errors
  • Servers MAY include retry guidance (e.g., Retry-After header in HTTP)
  • Servers SHOULD log system errors for diagnostic purposes
  • Example error codes: HTTP 500 Internal Server Error or 503 Service Unavailable, gRPC INTERNAL or UNAVAILABLE, JSON-RPC -32603 Internal error
  • Example scenarios: Database connection failure, downstream service timeout, rate limit exceeded

Error Payload Structure:

All error responses in the A2A protocol, regardless of binding, MUST convey the following information:

1. Error Code: A machine-readable identifier for the error type (e.g., string code, numeric code, or protocol-specific status)
2. Error Message: A human-readable description of the error
3. Error Details (optional): An array of objects providing additional structured information about the error. Each object in the array MUST include a @type key that identifies the object's type (using ProtoJSON Any representation). Well-known types from the google.rpc error model (e.g., ErrorInfo, BadRequest) SHOULD be used where applicable. Error details may be used for:
   • Affected fields or parameters
   • Contextual information (e.g., task ID, timestamp)
   • Suggestions for resolution

Protocol bindings MUST map these elements to their native error representations while preserving semantic meaning.

A2A-Specific Errors: