AdCP — Error Handling

AdCP uses a consistent error handling approach across all operations. Understanding error categories and implementing proper recovery strategies is essential for building robust integrations.

Compliance Levels

Sellers can adopt error handling incrementally. Each level builds on the previous:

Level	What to implement	What agents can do
Level 1	Return `code` + `message` on every error	Agents match on error code to classify failures
Level 2	Add `recovery`, `retry_after`, `field`, and `suggestion`	Agents auto-retry transient errors and self-correct correctable ones
Level 3	Use transport bindings to put errors in `structuredContent` (MCP) or artifact `DataPart` (A2A)	Programmatic clients get typed errors without parsing text

Level 1 is the minimum for a conformant implementation. Level 2 is where agent-driven recovery becomes possible — without recovery, agents must guess from the error code. Level 3 is where client libraries like @adcp/client can provide fully typed error objects.

Error Categories

1. Protocol Errors

Transport/connection issues not related to AdCP business logic:

Network timeouts
Connection refused
TLS/SSL errors
JSON parsing errors

Handling: Retry with exponential backoff.

2. Task Errors

Business logic failures returned as status: "failed":

Insufficient inventory
Invalid targeting
Budget validation failures
Resource not found

Handling: Check the recovery field to determine whether to retry, fix the request, or escalate.

3. Validation Errors

Malformed requests that fail schema validation:

Missing required fields
Invalid field types
Out-of-range values

Handling: Fix request format and retry. Usually development-time issues.

Error Response Format

Failed operations return status failed with error details. The error object follows the error.json schema:

{
  "status": "failed",
  "message": "Budget is below the seller's minimum for this product",
  "errors": [
    {
      "code": "BUDGET_TOO_LOW",
      "message": "Budget is below the seller's minimum for this product",
      "recovery": "correctable",
      "field": "budget.total",
      "suggestion": "Increase budget to at least 500 USD",
      "details": {
        "minimum_budget": 500,
        "currency": "USD"
      }
    }
  ]
}

Error Object Fields

These fields are defined by the error.json schema:

Field	Type	Required	Description
`code`	string	Yes	Machine-readable error code from the standard vocabulary or a seller-specific code
`message`	string	Yes	Human-readable error description
`recovery`	string	No	Agent recovery classification: `transient`, `correctable`, or `terminal`
`retry_after`	number	No	Seconds to wait before retrying (transient errors)
`field`	string	No	Field path that caused the error (e.g., `packages[0].targeting`)
`suggestion`	string	No	Suggested fix for the error
`details`	object	No	Additional context-specific information

Standard Error Codes

AdCP defines 20 standard error codes in error-code.json. Sellers MAY use codes not in this vocabulary for platform-specific errors. Agents MUST handle unknown codes by falling back to the recovery classification.

Authentication and Access

Code	Recovery	Description	Resolution
`AUTH_REQUIRED`	correctable	Authentication is required or credentials are invalid	Provide credentials via auth header
`ACCOUNT_NOT_FOUND`	terminal	Account reference could not be resolved	Verify via `list_accounts` or contact seller
`ACCOUNT_SETUP_REQUIRED`	correctable	Account needs setup before use	Check `details.setup` for URL or instructions
`ACCOUNT_AMBIGUOUS`	correctable	Natural key resolves to multiple accounts	Pass explicit `account_id` or a more specific natural key
`ACCOUNT_PAYMENT_REQUIRED`	terminal	Outstanding balance requires payment	Buyer must resolve billing
`ACCOUNT_SUSPENDED`	terminal	Account has been suspended	Contact seller to resolve

Request Validation

Code	Recovery	Description	Resolution
`INVALID_REQUEST`	correctable	Request is malformed or violates schema constraints	Check request parameters and fix
`UNSUPPORTED_FEATURE`	correctable	Requested feature not supported by this seller	Check `get_adcp_capabilities` and remove unsupported fields
`POLICY_VIOLATION`	correctable	Request violates content or advertising policies	Review policy requirements in the error details
`COMPLIANCE_UNSATISFIED`	correctable	Required disclosure cannot be satisfied by the target format	Choose a format that supports the required disclosure capabilities

Inventory and Products

Code	Recovery	Description	Resolution
`PRODUCT_NOT_FOUND`	correctable	Referenced product IDs are unknown or expired	Remove invalid IDs, or re-discover with `get_products`
`PRODUCT_UNAVAILABLE`	correctable	Product is sold out or no longer available	Choose a different product
`PROPOSAL_EXPIRED`	correctable	Referenced proposal has passed its `expires_at`	Run `get_products` to get a fresh proposal
`AUDIENCE_TOO_SMALL`	correctable	Audience segment below minimum size	Broaden targeting or upload more audience members

Budget and Creative

Code	Recovery	Description	Resolution
`BUDGET_TOO_LOW`	correctable	Budget below seller’s minimum	Increase budget or check `capabilities.media_buy.limits`
`BUDGET_EXHAUSTED`	terminal	Account or campaign budget fully spent	Buyer must add funds or increase budget cap
`CREATIVE_REJECTED`	correctable	Creative failed content policy review	Revise per seller’s `advertising_policies`

System

Code	Recovery	Description	Resolution
`RATE_LIMITED`	transient	Request rate exceeded	Wait for `retry_after` seconds, then retry
`SERVICE_UNAVAILABLE`	transient	Seller service temporarily unavailable	Retry with exponential backoff
`CONFLICT`	transient	Concurrent modification detected	Re-read the resource and retry with current state

Recovery Classification

Use the recovery field to determine how to handle errors:

Recovery	Meaning	Action
`transient`	Temporary failure (rate limit, service unavailable, conflict)	Retry after `retry_after` or with exponential backoff
`correctable`	Request can be fixed and resent (invalid field, budget too low, creative rejected)	Modify the request and retry
`terminal`	Requires human action (account suspended, payment required)	Escalate to a human operator

For unknown recovery values (forward compatibility), treat as terminal.

function isRetryable(error) {
  // Use recovery field when available
  if (error.recovery) {
    return error.recovery === 'transient';
  }

  // Network errors are retryable
  if (error.code === 'ECONNREFUSED' || error.code === 'ETIMEDOUT') {
    return true;
  }

  // Fall back to error code matching
  return ['RATE_LIMITED', 'SERVICE_UNAVAILABLE', 'CONFLICT'].includes(error.code);
}

Retry Logic

Exponential Backoff

Implement exponential backoff for retryable errors:

async function retryWithBackoff(fn, options = {}) {
  const {
    maxRetries = 3,
    baseDelay = 1000,
    maxDelay = 60000
  } = options;

  for (let attempt = 0; attempt <= maxRetries; attempt++) {
    try {
      return await fn();
    } catch (error) {
      if (!isRetryable(error) || attempt === maxRetries) {
        throw error;
      }

      // Use retry_after when available, otherwise exponential backoff
      const retryAfter = error.retry_after ||
        Math.min(baseDelay * Math.pow(2, attempt), maxDelay);

      // Add jitter to prevent thundering herd
      const jitter = retryAfter * (0.75 + Math.random() * 0.5);
      await sleep(jitter);
    }
  }
}

Rate Limit Handling

async function handleRateLimit(error, retryFn) {
  if (error.recovery !== 'transient' &&
      error.code !== 'RATE_LIMITED') {
    throw error;
  }

  const retryAfter = error.retry_after || 60;
  console.log(`Rate limited. Waiting ${retryAfter} seconds...`);

  await sleep(retryAfter * 1000);
  return retryFn();
}

Error Handling Patterns

Basic Error Handler

async function handleAdcpError(error) {
  // Use recovery classification when available
  switch (error.recovery) {
    case 'transient':
      const delay = error.retry_after
        ? error.retry_after * 1000
        : 5000;
      await sleep(delay);
      return retry();

    case 'correctable':
      // Surface suggestion so the request can be fixed
      if (error.suggestion) {
        console.log('Suggestion:', error.suggestion);
      }
      if (error.field) {
        console.log('Problem field:', error.field);
      }
      throw error;

    case 'terminal':
      console.error('Terminal error:', error.message);
      throw error;
  }

  // Fall back to error code matching
  switch (error.code) {
    case 'AUTH_REQUIRED':
      await refreshCredentials();
      return retry();

    case 'INVALID_REQUEST':
      console.error('Validation error:', error);
      throw error;

    default:
      console.error('AdCP error:', error);
      throw error;
  }
}

User-Friendly Messages

Convert technical errors to user-friendly messages:

const USER_MESSAGES = {
  'RATE_LIMITED': 'Too many requests. Please wait a moment and try again.',
  'BUDGET_TOO_LOW': 'This is below the seller\'s minimum budget. Increase your budget.',
  'PRODUCT_NOT_FOUND': 'One or more products could not be found. Try searching again.',
  'ACCOUNT_SUSPENDED': 'Your account has been suspended. Contact the seller to resolve.',
  'SERVICE_UNAVAILABLE': 'The service is temporarily unavailable. Please try again in a few minutes.',
  'CREATIVE_REJECTED': 'Your creative did not pass policy review. Check the suggestion for details.',
  'AUDIENCE_TOO_SMALL': 'Your target audience is too small. Try broadening your targeting.'
};

function getUserMessage(code, fallbackMessage) {
  return USER_MESSAGES[code] || fallbackMessage || 'An unexpected error occurred. Please try again.';
}

Structured Error Logging

Log errors with context for debugging:

function logError(error, context = {}) {
  console.error('AdCP Error:', {
    code: error.code,
    recovery: error.recovery,
    message: error.message,
    field: error.field,
    timestamp: new Date().toISOString(),
    ...context,
    // Don't log sensitive data
    // NO: credentials, briefs, PII
  });
}

Webhook Error Handling

Failed Webhook Delivery

When webhook delivery fails, fall back to polling:

class WebhookErrorHandler {
  async onDeliveryFailure(taskId, error) {
    console.warn(`Webhook delivery failed for ${taskId}:`, error);

    // Start polling as fallback
    this.startPolling(taskId);

    // Track failure for monitoring
    this.metrics.incrementCounter('webhook_failures');
  }

  async startPolling(taskId) {
    const response = await adcp.call('tasks/get', {
      task_id: taskId,
      include_result: true
    });

    if (['completed', 'failed', 'canceled'].includes(response.status)) {
      await this.processResult(taskId, response);
    } else {
      // Schedule next poll
      setTimeout(() => this.startPolling(taskId), 30000);
    }
  }
}

Webhook Handler Errors

Handle errors in your webhook endpoint gracefully:

app.post('/webhooks/adcp', async (req, res) => {
  try {
    // Always respond quickly
    res.status(200).json({ status: 'received' });

    // Process asynchronously
    await processWebhookAsync(req.body);
  } catch (error) {
    // Log error but don't fail the response
    console.error('Webhook processing error:', error);

    // Move to dead letter queue for investigation
    await deadLetterQueue.add(req.body, error);
  }
});

Recovery Strategies

Context Recovery

If context expires, start a new conversation:

async function callWithContextRecovery(request) {
  try {
    return await adcp.call(request);
  } catch (error) {
    if (error.code === 'INVALID_REQUEST' &&
        error.message?.includes('context not found')) {
      // Clear stale context and retry
      delete request.context_id;
      return await adcp.call(request);
    }
    throw error;
  }
}

Partial Success Handling

Some operations may partially succeed:

{
  "status": "completed",
  "message": "Created media buy with warnings",
  "media_buy_id": "mb_123",
  "errors": [
    {
      "code": "COMPLIANCE_UNSATISFIED",
      "message": "Required disclosure position not supported by one placement",
      "field": "packages[0].placements[2]",
      "suggestion": "Choose a format that supports the required disclosure positions"
    }
  ]
}

Handle partial success:

function handlePartialSuccess(response) {
  if (response.status === 'completed' && response.errors?.length) {
    // Show warnings to user
    for (const warning of response.errors) {
      showWarning(warning.message, warning.suggestion);
    }
  }

  // Continue with successful result
  return response;
}

Governance Error Patterns

check_governance returns a status field rather than an error object. Governance results are not errors in the protocol sense — they are decisions. Handle them separately from AdCP task errors.

Governance status	Meaning	Action
`approved`	Plan passes governance	Proceed
`conditions`	Approved with constraints	Apply conditions, re-check
`denied`	Plan violates governance	Block the operation

If the governance agent needs human review internally (e.g., the action exceeds the agent’s authority), check_governance behaves like any async task — it returns submitted/working status and eventually resolves to approved or denied. Handle this with the standard async task lifecycle, not special-case logic. Governance errors from the protocol layer (as opposed to governance decisions) use the standard error format. The most common:

Code	Recovery	When it occurs
`PLAN_NOT_FOUND`	correctable	`sync_plans` was not called before `check_governance`
`INVALID_REQUEST`	correctable	Missing required fields (e.g., `plan_id`, `caller`)
`AUTH_REQUIRED`	correctable	Governance agent requires authentication

Best Practices

Check recovery first — it’s the most reliable signal for how to handle an error
Implement retries — use exponential backoff for transient errors
Respect rate limits — honor retry_after values
Handle unknown codes gracefully — fall back to the recovery classification
Log with context — include code, recovery, and field for debugging
Fallback strategies — always have a backup (e.g., polling for webhooks)
Don’t retry terminal errors — escalate to a human operator
Handle partial success — process warnings in successful responses

Next Steps

Transport Bindings: See Transport Errors for how errors travel over MCP and A2A
Task Lifecycle: See Task Lifecycle for status handling
Webhooks: See Webhooks for webhook error handling
Security: See Security for authentication errors

Documentation

​Compliance Levels

​Error Categories

​1. Protocol Errors

​2. Task Errors

​3. Validation Errors

​Error Response Format

​Error Object Fields

​Standard Error Codes

​Authentication and Access

​Request Validation

​Inventory and Products

​Budget and Creative

​System

​Recovery Classification

​Retry Logic

​Exponential Backoff

​Rate Limit Handling

​Error Handling Patterns

​Basic Error Handler

​User-Friendly Messages

​Structured Error Logging

​Webhook Error Handling

​Failed Webhook Delivery

​Webhook Handler Errors

​Recovery Strategies

​Context Recovery

​Partial Success Handling

​Governance Error Patterns

​Best Practices

​Next Steps