Appendix H: Error Code Reference

This appendix provides a comprehensive reference of all error codes, their HTTP status mappings, and recommended handling strategies.

Error Code Categories

Pierre uses four primary error enums:

ErrorCode - Application-level error codes with HTTP mapping
DatabaseError - Database operation errors
ProviderError - Fitness provider API errors
ProtocolError - Protocol operation errors (MCP/A2A)

ErrorCode → HTTP Status Mapping

Source: src/errors.rs:17-86

Authentication & Authorization (4xx)

Error Code	HTTP Status	Description	Client Action
`AuthRequired`	401	No authentication provided	Prompt user to login
`AuthInvalid`	401	Invalid credentials	Re-authenticate
`AuthExpired`	403	Token has expired	Refresh token or re-login
`AuthMalformed`	403	Token is corrupted	Re-authenticate
`PermissionDenied`	403	Insufficient permissions	Request access or escalate

Rate Limiting (429)

Error Code	HTTP Status	Description	Client Action
`RateLimitExceeded`	429	Too many requests	Implement exponential backoff
`QuotaExceeded`	429	Monthly quota exceeded	Upgrade tier or wait for reset

Validation (400)

Error Code	HTTP Status	Description	Client Action
`InvalidInput`	400	Input validation failed	Fix input and retry
`MissingRequiredField`	400	Required field missing	Include required fields
`InvalidFormat`	400	Data format incorrect	Check API documentation
`ValueOutOfRange`	400	Value outside bounds	Use valid value range

Resource Management (4xx)

Error Code	HTTP Status	Description	Client Action
`ResourceNotFound`	404	Resource doesn’t exist	Check resource ID
`ResourceAlreadyExists`	409	Duplicate resource	Use existing or rename
`ResourceLocked`	409	Resource is locked	Wait and retry
`ResourceUnavailable`	503	Temporarily unavailable	Retry with backoff

External Services (5xx)

Error Code	HTTP Status	Description	Client Action
`ExternalServiceError`	502	Provider returned error	Retry or report issue
`ExternalServiceUnavailable`	502	Provider is down	Retry later
`ExternalAuthFailed`	503	Provider auth failed	Re-connect provider
`ExternalRateLimited`	503	Provider rate limited	Wait for provider reset

Configuration (500)

Error Code	HTTP Status	Description	Client Action
`ConfigError`	500	Configuration error	Contact administrator
`ConfigMissing`	500	Missing configuration	Contact administrator
`ConfigInvalid`	500	Invalid configuration	Contact administrator

Internal Errors (500)

Error Code	HTTP Status	Description	Client Action
`InternalError`	500	Unexpected server error	Retry, then report
`DatabaseError`	500	Database operation failed	Retry, then report
`StorageError`	500	Storage operation failed	Retry, then report
`SerializationError`	500	JSON parsing failed	Check request format

DatabaseError Variants

Source: src/database/errors.rs:10-140

Variant	Context Fields	Typical Cause
`NotFound`	`entity_type`, `entity_id`	Query returned no rows
`TenantIsolationViolation`	`entity_type`, `entity_id`, `requested_tenant`, `actual_tenant`	Cross-tenant access attempt
`EncryptionFailed`	`context`	Encryption key issue
`DecryptionFailed`	`context`	AAD mismatch or corrupt data
`ConstraintViolation`	`constraint`, `details`	Unique/foreign key violation
`ConnectionError`	message	Pool exhausted or network
`QueryError`	`context`	SQL syntax or type error
`MigrationError`	`version`, `details`	Schema migration failed
`InvalidData`	`field`, `reason`	Data type mismatch
`PoolExhausted`	`max_connections`, `wait_time_ms`	Too many concurrent queries
`TransactionRollback`	`reason`	Explicit rollback
`SchemaMismatch`	`expected`, `actual`	Database version mismatch
`Timeout`	`operation`, `timeout_secs`	Query took too long
`TransactionConflict`	`details`	Deadlock or serialization failure

ProviderError Variants

Source: src/providers/errors.rs:11-80

Variant	Context Fields	Retry Strategy
`ApiError`	`provider`, `status_code`, `message`, `retryable`	Check `retryable` field
`RateLimitExceeded`	`provider`, `retry_after_secs`, `limit_type`	Wait `retry_after_secs`
`AuthenticationFailed`	`provider`, `reason`	Re-authenticate user
`TokenExpired`	`provider`	Auto-refresh token
`InvalidResponse`	`provider`, `context`	Log and skip activity
`NetworkError`	`provider`, `message`	Retry with backoff
`Timeout`	`provider`, `timeout_secs`	Increase timeout or retry
`NotSupported`	`provider`, `feature`	Feature unavailable

ProtocolError Variants

Source: src/protocols/mod.rs:35-211

Protocol errors for MCP and A2A protocol operations:

Tool Errors

Variant	Context Fields	Typical Cause
`ToolNotFound`	`tool_id`, `available_count`	Tool ID doesn’t exist
`InvalidParameter`	`tool_id`, `parameter`, `reason`	Parameter validation failed
`MissingParameter`	`tool_id`, `parameter`	Required parameter not provided
`InvalidParameters`	message	General parameter error
`ExecutionFailed`	message	Tool execution error
`ExecutionFailedDetailed`	`tool_id`, `source`	Tool execution with source error

Protocol Errors

Variant	Context Fields	Typical Cause
`UnsupportedProtocol`	`protocol`	Protocol type not supported
`InvalidRequest`	message	Malformed request
`InvalidRequestDetailed`	`protocol`, `reason`	Request validation failure
`ConversionFailed`	`from`, `to`, `reason`	Protocol format conversion error

Configuration Errors

Variant	Context Fields	Typical Cause
`ConfigMissing`	`key`	Required config not set
`ConfigurationError`	message	General config error
`ConfigurationErrorDetailed`	`message`	Config error with details

Plugin Errors

Variant	Context Fields	Typical Cause
`PluginNotFound`	`plugin_id`	Plugin ID doesn’t exist
`PluginError`	`plugin_id`, `details`	Plugin execution failed

Access Control Errors

Variant	Context Fields	Typical Cause
`InsufficientSubscription`	`required`, `current`	User tier too low
`RateLimitExceeded`	`requests`, `window_secs`	Too many requests

Other Errors

Variant	Context Fields	Typical Cause
`Serialization`	`context`, `source`	JSON serialization failed
`SerializationError`	message	Simple serialization error
`Database`	`source`	Database operation failed
`InvalidSchema`	`entity`, `reason`	Schema validation error
`InternalError`	message	Unexpected server error
`OperationCancelled`	message	User cancelled operation

JSON Error Response Format

All API errors return a consistent JSON structure:

{
  "error": {
    "code": "auth_expired",
    "message": "The authentication token has expired",
    "details": {
      "expired_at": "2025-01-15T10:30:00Z",
      "token_type": "access_token"
    },
    "request_id": "req_abc123"
  }
}

Fields:

code: Machine-readable error code (snake_case)
message: Human-readable description
details: Optional context-specific data
request_id: Correlation ID for debugging

MCP Error Response Format

For MCP protocol, errors follow JSON-RPC 2.0 spec:

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32600,
    "message": "Invalid Request",
    "data": {
      "pierre_code": "invalid_input",
      "details": "Missing required field: provider"
    }
  }
}

JSON-RPC Error Codes:

Code	Meaning	Pierre Mapping
-32700	Parse error	`SerializationError`
-32600	Invalid Request	`InvalidInput`
-32601	Method not found	`ResourceNotFound`
-32602	Invalid params	`InvalidInput`
-32603	Internal error	`InternalError`
-32000 to -32099	Server error	Application-specific

Retry Strategies

Exponential Backoff

#![allow(unused)]
fn main() {
// Standard retry with exponential backoff
let delays = [100, 200, 400, 800, 1600]; // milliseconds

for (attempt, delay) in delays.iter().enumerate() {
    match operation().await {
        Ok(result) => return Ok(result),
        Err(e) if e.is_retryable() => {
            tokio::time::sleep(Duration::from_millis(*delay)).await;
        }
        Err(e) => return Err(e),
    }
}
}

Rate Limit Handling

#![allow(unused)]
fn main() {
match provider.get_activities().await {
    Err(ProviderError::RateLimitExceeded { retry_after_secs, .. }) => {
        // Respect Retry-After header
        tokio::time::sleep(Duration::from_secs(retry_after_secs)).await;
        provider.get_activities().await
    }
    result => result,
}
}

Error Logging

All errors are logged with structured context:

#![allow(unused)]
fn main() {
tracing::error!(
    error_code = %error.code(),
    http_status = error.http_status(),
    request_id = %request_id,
    user_id = %user_id,
    "Operation failed: {}", error
);
}

Key Takeaways

Consistent HTTP mapping: ErrorCode::http_status() provides standardized status codes.
Structured context: All errors include relevant context fields for debugging.
Retry guidance: retryable field and retry_after_secs guide client behavior.
Tenant isolation: TenantIsolationViolation is a security-critical error.
JSON-RPC compliance: MCP errors follow JSON-RPC 2.0 specification.
Request correlation: All errors include request_id for distributed tracing.

Related Chapters:

Chapter 2: Error Handling (structured error patterns)
Chapter 9: JSON-RPC Foundation (MCP error codes)
Appendix E: Rate Limiting (quota errors)

Keyboard shortcuts

Pierre MCP Server Tutorial