Error Categories

Pingward classifies test failures into categories to help you understand and respond to issues.

Category List

Connection Errors

Category	Description	Common Causes
Timeout	Request exceeded timeout limit	Slow server, network issues, server overload
ConnectionRefused	Server rejected the connection	Server down, wrong port, firewall
DnsResolutionFailed	Could not resolve hostname	DNS misconfiguration, domain expired
SslCertificateError	TLS/SSL handshake failed	Expired certificate, invalid cert, hostname mismatch
ConnectionReset	Connection was reset	Server crash, network interruption
RedirectLoop	Too many redirects	Misconfigured redirects

HTTP Errors

Category	Description	HTTP Codes
ServiceUnavailable	Server cannot handle request	502, 503, 504
ServerError	Server-side error	500, 501, other 5xx
BadRequest	Client error in request	400
AuthenticationFailed	Authentication required/failed	401
Forbidden	Access denied	403
NotFound	Resource not found	404
RateLimited	Too many requests	429
ClientError	Other client errors	Other 4xx

Validation Errors

Category	Description
AssertionFailed	Response didn't match assertions
ContentMismatch	Response content unexpected
BodyTooLarge	Response exceeded size limit

MCP Protocol Errors

Category	Description
McpProtocolNegotiationFailure	MCP initialize handshake failed or returned an error
McpCapabilityMismatch	Server does not advertise expected capabilities
McpToolInvocationFailure	Canary tool invocation returned an error
McpResourceAccessFailure	Canary resource read failed
McpSessionFailure	Session management error, timeout, or unexpected failure

A2A Protocol Errors

Category	Description
A2aAgentCardDiscoveryFailure	Agent card unreachable, returned HTTP error, or invalid JSON
A2aTaskLifecycleFailure	Probe task failed, was rejected, or returned an error
A2aSkillMismatch	Expected skills not found in agent card
A2aTaskTimeout	Probe task did not complete within the configured timeout
A2aUnsupportedOperation	Expected capabilities not supported by agent

GraphQL Errors

Category	Description
GraphQlIntrospectionFailure	Introspection query failed or is disabled
GraphQlSchemaValidationError	Schema doesn't match expected types or fields
GraphQlQueryError	Canary query returned GraphQL errors
GraphQlTransportError	HTTP transport failure for GraphQL endpoint
GraphQlAuthorizationError	Query-level authorization failure

gRPC Errors

Category	Description
GrpcConnectionFailure	Cannot establish gRPC HTTP/2 connection
GrpcHealthCheckFailure	Health check returned NOT_SERVING or SERVICE_UNKNOWN
GrpcServiceNotFound	Service not found via health check
GrpcDeadlineExceeded	gRPC call exceeded deadline
GrpcPermissionDenied	PERMISSION_DENIED or UNAUTHENTICATED status
GrpcUnavailable	gRPC server is unavailable

Other

Category	Description
Unknown	Unclassified error

Default Severities

Each category has a default severity that reflects its typical impact:

Critical (Immediate Action)

• ServiceUnavailable
• Timeout
• ConnectionRefused
• DnsResolutionFailed
• McpProtocolNegotiationFailure
• A2aAgentCardDiscoveryFailure
• GrpcConnectionFailure
• GrpcHealthCheckFailure
• GraphQlTransportError
• GrpcUnavailable

High (Urgent)

• SslCertificateError
• ServerError
• ConnectionReset
• RedirectLoop
• McpToolInvocationFailure
• McpSessionFailure
• A2aTaskLifecycleFailure
• A2aTaskTimeout
• GraphQlIntrospectionFailure
• GraphQlQueryError
• GraphQlAuthorizationError
• GrpcDeadlineExceeded
• GrpcPermissionDenied

Medium (Important)

• AssertionFailed
• AuthenticationFailed
• Forbidden
• RateLimited
• ContentMismatch
• McpCapabilityMismatch
• McpResourceAccessFailure
• A2aSkillMismatch
• A2aUnsupportedOperation
• GraphQlSchemaValidationError
• GrpcServiceNotFound

Low (Minor)

• BadRequest
• NotFound
• ClientError
• BodyTooLarge
• Unknown

Customizing Severity

You can change the severity for any category in Settings → Severity.

Common customizations:

• NotFound → Critical: For critical resources that must exist
• Timeout → Medium: For known-slow APIs
• AssertionFailed → High: For critical validation checks

Using Categories in Routing

Route alerts based on error category:

Conditions:
  Error Categories: Timeout, ConnectionRefused, ServiceUnavailable

Actions:
  → PagerDuty (Infrastructure Team)

Conditions:
  Error Categories: AssertionFailed, ContentMismatch

Actions:
  → Slack #api-team

Troubleshooting by Category

Timeout

• Check server response times
• Look for resource exhaustion
• Check network path
• Consider increasing timeout threshold

ConnectionRefused

• Verify server is running
• Check correct port
• Review firewall rules
• Check security groups

DnsResolutionFailed

• Verify domain name is correct
• Check DNS propagation
• Review DNS server configuration
• Check for domain expiration

SslCertificateError

• Check certificate expiration
• Verify certificate chain
• Ensure hostname matches
• Update root certificates

ServiceUnavailable

• Check upstream dependencies
• Review server capacity
• Look for deployment issues
• Check load balancer health

McpProtocolNegotiationFailure

• Verify the MCP server is running and reachable
• Check the endpoint URL is correct (must support streamable HTTP)
• Verify the protocol version is supported by the server
• Check authentication headers if required

McpCapabilityMismatch

• Verify the server advertises the expected capabilities
• Check if a server update removed capabilities
• Update expected capabilities in test configuration

McpToolInvocationFailure

• Verify the canary tool name is correct
• Check the tool arguments are valid JSON
• Look for tool-specific error messages in the result

McpResourceAccessFailure

• Verify the canary resource URI is correct
• Check the resource exists on the server
• Look for permission errors

McpSessionFailure

• Check for server timeouts or restarts
• Review server logs for session errors
• Verify session management is working correctly

A2aAgentCardDiscoveryFailure

• Verify the base URL is correct
• Check that /.well-known/a2a/agent-card is accessible
• Verify the agent card is valid JSON with a name field
• Check authentication if the agent card is protected

A2aTaskLifecycleFailure

• Check agent logs for task processing errors
• Verify the probe task message is valid
• Look for JSON-RPC error codes in the result

A2aSkillMismatch

• Verify the expected skill IDs match the agent card
• Check if an agent update removed skills
• Update expected skills in test configuration

A2aTaskTimeout

• Increase the probe task timeout in test configuration
• Check if the agent is under heavy load
• Verify the agent is processing tasks correctly

A2aUnsupportedOperation

• Verify the expected capabilities match the agent card
• Check if an agent update removed capabilities
• Update expected capabilities in test configuration

GraphQlIntrospectionFailure

• Verify the GraphQL endpoint URL is correct
• Check if introspection is disabled on the server
• Verify authentication credentials if introspection requires authorization
• Check server logs for introspection query errors

GraphQlSchemaValidationError

• Verify the expected types and fields match the current schema
• Check if a recent deployment changed the schema
• Update expected types and fields in test configuration
• Review schema migration history

GraphQlQueryError

• Verify the canary query syntax is valid
• Check that canary variables match the query's expected input
• Look for resolver errors in the server logs
• Verify the queried data exists

GraphQlTransportError

• Verify the GraphQL endpoint URL is correct and reachable
• Check for DNS resolution or network connectivity issues
• Verify the server is running and accepting HTTP requests
• Check for TLS/SSL certificate issues

GraphQlAuthorizationError

• Verify authentication tokens or API keys are valid and not expired
• Check that the authenticated user has permission for the query
• Review field-level authorization rules on the server
• Check for CORS issues if applicable

GrpcConnectionFailure

• Verify the gRPC server address and port are correct
• Check that the server supports HTTP/2
• Verify TLS configuration if using secure connections
• Check firewall rules and network connectivity

GrpcHealthCheckFailure

• Verify the gRPC health checking service is implemented
• Check the service-specific health status if a service name is configured
• Review server logs for health check handler errors
• Verify the health check service is registered correctly

GrpcServiceNotFound

• Verify the service name is fully qualified (e.g., "package.ServiceName")
• Check that the service is registered with the health check provider
• Verify server reflection is enabled if using service discovery
• Check if a recent deployment removed the service

GrpcDeadlineExceeded

• Increase the timeout in test configuration
• Check server response times and resource utilization
• Look for slow dependencies or database queries
• Verify network latency between Pingward and the server

GrpcPermissionDenied

• Verify the auth token is valid and not expired
• Check that the token has the required scopes or roles
• Review server-side authorization policies
• Check for IP-based access restrictions

GrpcUnavailable

• Verify the gRPC server is running
• Check load balancer health and configuration
• Review server resource utilization (CPU, memory)
• Check for recent deployments or configuration changes