エラーハンドリング

{
  "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"
      }
    }
  ]
}

// MCP — structuredContent AND payload both carry the error
{
  "content": [{"type": "text", "text": "{\"adcp_error\":{\"code\":\"BUDGET_TOO_LOW\", ...}}"}],
  "isError": true,
  "structuredContent": {
    "adcp_error": { "code": "BUDGET_TOO_LOW", "message": "...", "recovery": "correctable" },
    "payload": {
      "errors": [
        { "code": "BUDGET_TOO_LOW", "message": "...", "recovery": "correctable", "field": "budget.total" }
      ]
    }
  }
}

// A2A — artifact DataPart carries adcp_error; if the agent also surfaces payload via a sibling DataPart, errors[] lives there
{
  "status": { "state": "failed" },
  "artifacts": [{
    "artifactId": "error-result",
    "parts": [
      { "kind": "data", "data": { "adcp_error": { "code": "BUDGET_TOO_LOW", ... } } },
      { "kind": "data", "data": { "errors": [{ "code": "BUDGET_TOO_LOW", "field": "budget.total", ... }] } }
    ]
  }]
}

async function syncAccountsWithRecovery(client, account) {
  const result = await client.syncAccounts({ accounts: [account] });
  const error = result.accounts[0]?.errors?.[0];
  if (!error) return result;

  switch (error.code) {
    case 'BILLING_NOT_SUPPORTED': {
      // Seller-wide or per-account gate. Check capabilities, dispatch on scope.
      const scope = error.details?.scope;  // "capability" | "account"
      if (scope === 'capability') {
        // The seller never accepts this value. Pick from supported_billing.
        const supported = error.details?.supported_billing ?? [];
        if (supported.length === 0) return surfaceToHuman(error);
        return client.syncAccounts({
          accounts: [{ ...account, billing: supported[0] }],
        });
      }
      // Per-account-relationship reject — the operator-on-this-account isn't
      // billable directly. Try the next-most-permissive value the seller's
      // capability allows.
      return tryNextBillingValue(client, account, error);
    }

    case 'BILLING_NOT_PERMITTED_FOR_AGENT': {
      // Per-buyer-agent commercial gate. Autonomous retry only when the seller
      // suggests a fallback; otherwise surface — the agent cannot extend its
      // own commercial relationship.
      const suggested = error.details?.suggested_billing;
      if (!suggested) return surfaceToHuman(error);
      return client.syncAccounts({
        accounts: [{ ...account, billing: suggested }],
      });
    }

    default:
      throw error;
  }
}

{
  "accounts": [{
    "brand": { "domain": "nova-brands.com", "brand_id": "spark" },
    "operator": "pinnacle-media.com",
    "action": "failed",
    "status": "rejected",
    "errors": [{
      "code": "BILLING_NOT_PERMITTED_FOR_AGENT",
      "message": "This buyer agent is onboarded as passthrough-only; only operator billing is permitted.",
      "recovery": "correctable",
      "details": {
        "rejected_billing": "agent",
        "suggested_billing": "operator"
      }
    }]
  }]
}

{
  "adcp_error": {
    "code": "FIELD_NOT_PERMITTED",
    "message": "Caller's field_scopes for update_media_buy does not include this field",
    "recovery": "correctable",
    "field": "packages[0].budget"
  },
  "payload": {
    "errors": [
      {
        "code": "FIELD_NOT_PERMITTED",
        "message": "Caller's field_scopes for update_media_buy does not include this field",
        "recovery": "correctable",
        "field": "packages[0].budget",
        "details": {
          "task": "update_media_buy",
          "permitted_fields": ["reporting_webhook"]
        }
      }
    ]
  }
}

async function dispatchAuthzError(error) {
  // Per-agent commercial status — code is the discriminator, no details payload.
  if (error.code === 'AGENT_SUSPENDED' || error.code === 'AGENT_BLOCKED') {
    return surfaceToHuman({ code: error.code });
  }

  if (error.code !== 'PERMISSION_DENIED') throw error;

  // Generic credential-shaped failure — no scope on details.
  if (!error.details?.scope) {
    return refreshGovernanceContextAndRetry(error);
  }

  // Per-agent provisioning gate — terminal-pending-onboarding.
  if (error.details?.scope === 'agent') {
    const { reason } = error.details;
    // reason: 'sandbox_only'
    return surfaceToHuman({ code: error.code, reason });
  }

  throw error;  // Unknown scope — surface rather than guess.
}

{
  "adcp_error": {
    "code": "AGENT_SUSPENDED",
    "message": "Buyer agent's commercial relationship with this seller is suspended.",
    "recovery": "terminal"
  }
}

{
  "adcp_error": {
    "code": "PERMISSION_DENIED",
    "message": "This buyer agent is provisioned for sandbox traffic only.",
    "recovery": "correctable",
    "details": {
      "scope": "agent",
      "reason": "sandbox_only"
    }
  }
}

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);
}

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);
    }
  }
}

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();
}

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;
  }
}

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.';
}

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
  });
}

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);
    }
  }
}

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);
  }
});

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;
  }
}

{
  "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"
    }
  ]
}

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;
}

{
  "code": "CONFIGURATION_ERROR",
  "message": "account is mode='mock' but no mock_upstream_url declared in metadata; populate it in the AccountStore",
  "recovery": "terminal"
}

{
  "code": "CONFIGURATION_ERROR",
  "message": "configuration error",
  "recovery": "terminal"
}

{
  "code": "CONFIGURATION_ERROR",
  "message": "ECONNREFUSED postgres://admin:hunter2@10.0.1.42:5432/prod (at /opt/seller/src/db/pool.ts:127)",
  "recovery": "terminal"
}