Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.adcontextprotocol.org/llms.txt

Use this file to discover all available pages before exploring further.

This document outlines AdCP’s approach to error handling across MCP and A2A protocols, providing consistent patterns for both fatal errors and non-fatal warnings.

​
Philosophy

​
Pending States vs Errors

Pending States (Normal Flow):
  • pending: Request received and queued
  • processing: Operation in progress
  • pending_manual: Operation requires human approval
  • pending_permission: Operation blocked by permissions
  • pending_approval: Awaiting ad server approval
These are NOT errors and should be handled as part of normal operation flow. Error States (Exceptional):
  • Task-level failures that prevent completion
  • Authentication failures
  • Invalid parameters
  • Resource not found
  • Authorization denied

​
Error Response Patterns

AdCP uses a two-tier error handling approach:
  1. Task-Level Errors (Non-Fatal): Warnings and issues that don’t prevent operation completion
  2. Protocol-Level Errors (Fatal): Operations that cannot be completed

​
Task-Level Error Handling

​
Non-Fatal Errors vs Warnings

AdCP distinguishes between two types of task-level issues: Non-Fatal Errors: Actual failures that prevented part of the request from being fulfilled. These go in the errors array: 
{
  "message": "Signal discovery completed with partial results",
  "context_id": "ctx-123",
  "signals": [/* available signals */],
  "errors": [
    {
      "code": "NO_DATA_IN_REGION",
      "message": "No signal data available for requested region: Australia",
      "field": "deliver_to.countries[1]",
      "suggestion": "Remove Australia from target countries or contact data provider for coverage expansion",
      "details": {
        "requested_country": "AU",
        "available_countries": ["US", "CA", "GB", "DE"],
        "data_provider": "Peer39"
      }
    }
  ]
}
Warnings: Advisory information about configuration, timing, or data quality. These are communicated only in the message field: 
{
  "message": "Signal activation successful. Note that your account frequency cap settings are set conservatively and may limit reach. Contact your account manager to review frequency cap settings for optimal performance.",
  "context_id": "ctx-456",
  "task_id": "activation_789",
  "status": "deployed",
  "decisioning_platform_segment_id": "pm_brand456_peer39_lux_auto",
  "deployed_at": "2025-01-15T14:30:00Z"
}

​
Partial Success Support

Tasks can succeed while returning non-fatal errors in the errors array or warnings in the message field: Non-Fatal Errors (partial failures in errors array):
  • Discovery tasks: Can find some results while reporting regions/platforms with no data
  • Activation tasks: Can activate on some platforms while failing on others
  • Creation tasks: Can create some packages while others fail validation
Warnings (advisory information in message field):
  • Discovery tasks: Can find results while noting data freshness or coverage limitations in the message
  • Activation tasks: Can activate successfully while noting suboptimal configuration in the message
  • Creation tasks: Can create resources while suggesting optimization opportunities in the message

​
Error Object Structure

The errors array contains error objects for actual failures: 
{
  "code": "ERROR_CODE",           // Required: Standardized error code
  "message": "Description",       // Required: Human-readable message
  "field": "field.path",         // Optional: Which field has the issue
  "suggestion": "Try this",      // Optional: Actionable remediation steps
  "details": {                   // Optional: Additional context
    "affected_items": ["id1"],
    "retry_after": 1800
  }
}

​
Warning Communication

Warnings and advisory information should be communicated in the human-readable message field rather than cluttering the errors array. This keeps the errors array focused on actionable failures that require programmatic handling.

​
Protocol-Level Error Handling

​
MCP (Model Context Protocol)

For fatal errors that prevent task completion, MCP uses the isError: true pattern: 
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "Failed to activate signal: Account 'brand-456-pm' not authorized for Peer39 data on PubMatic. Contact your PubMatic account manager to enable access."
      }
    ],
    "isError": true
  }
}
When to use MCP fatal errors:
  • Authentication failures
  • Invalid tool parameters
  • Resource not found
  • Authorization denied
  • System errors

​
A2A (Agent-to-Agent Protocol)

For fatal errors, A2A uses the status: "failed" pattern: 
{
  "taskId": "task_123",
  "status": "failed",
  "message": {
    "parts": [{
      "kind": "text",
      "text": "Unable to complete signal activation: Invalid signal agent segment ID 'seg_invalid_123'. Use get_signals to find current segment IDs."
    }]
  }
}
When to use A2A fatal errors:
  • Skill execution failures
  • Invalid request parameters
  • External service unavailable
  • Authentication issues

​
Error Recovery Strategies

​
Retry Logic

  • Check retry_after field for appropriate retry timing
  • Implement exponential backoff for rate limiting and service issues
  • Categorize errors by retry-ability (permanent vs temporary)
const RETRYABLE_ERRORS = [
  'RATE_LIMIT_EXCEEDED',
  'TIMEOUT', 
  'SERVICE_UNAVAILABLE',
  'ACTIVATION_FAILED'  // May succeed on retry
];

const PERMANENT_ERRORS = [
  'INVALID_CREDENTIALS',
  'INSUFFICIENT_PERMISSIONS',
  'SIGNAL_AGENT_SEGMENT_NOT_FOUND',
  'PLATFORM_UNAUTHORIZED'
];

​
Actionable Feedback

  • Use suggestion field to guide remediation steps
  • Include relevant context in details object for debugging
  • Provide specific field paths for validation errors
  • Reference external resources when additional action is required

​
Context Preservation

  • Use context_id for session management across related operations
  • Include task_id for asynchronous operation tracking
  • Preserve request context in error details for debugging

​
Implementation Guidelines

​
Error Message Construction

Good error messages:
  • Explain what went wrong and why
  • Provide specific remediation steps
  • Include relevant context (IDs, values, constraints)
  • Use clear, non-technical language
Example: 
{
  "code": "TARGETING_TOO_NARROW",
  "message": "Package targeting yielded 0 available impressions",
  "field": "packages[1].targeting_overlay",
  "suggestion": "Broaden geographic targeting or remove segment exclusions",
  "details": {
    "requested_budget": 40000,
    "available_impressions": 0,
    "affected_package": "nike_audio_drive_package"
  }
}

​
Error Code Naming

  • Use SCREAMING_SNAKE_CASE format
  • Be specific and descriptive
  • Group by category (ACTIVATION_, TARGETING_, PRICING_, etc.)
  • Avoid generic codes like ERROR or FAILED

​
Validation Error Patterns

For field validation issues: 
{
  "code": "INVALID_FIELD_VALUE",
  "message": "Budget must be between $1,000 and $1,000,000",
  "field": "packages[0].budget.total",
  "suggestion": "Adjust budget to be within allowed range",
  "details": {
    "provided_value": 500,
    "min_value": 1000,
    "max_value": 1000000,
    "currency": "USD"
  }
}

​
Common Error Scenarios

​
Authentication & Authorization

  • Invalid credentials: Protocol-level fatal error
  • Insufficient permissions: Protocol-level fatal error
  • Account restrictions: Task-level warning with limited functionality

​
Resource Management

  • Resource not found: Protocol-level fatal error
  • Resource unavailable: Task-level warning with alternatives
  • Resource limitations: Task-level warning with impact description

​
Data Quality Issues

  • Invalid input data: Protocol-level fatal error
  • Stale data: Task-level warning communicated in message field
  • Incomplete data: Task-level warning communicated in message field

​
Testing Error Scenarios

When implementing AdCP tasks, test these error scenarios:
  1. Invalid authentication → Protocol-level fatal
  2. Missing required fields → Protocol-level fatal
  3. Field validation failures → Protocol-level fatal
  4. Resource limitations → Task-level warnings in message field
  5. Partial data issues → Task-level warnings in message field
  6. Service degradation → Task-level warnings in message field with retry guidance

​
Reference