From df2bfefab3aba56db515e0314b61f2b2a34ec706 Mon Sep 17 00:00:00 2001 From: Aleksander Sekowski Date: Sun, 5 Jul 2026 17:18:02 -0700 Subject: [PATCH] fix(docs): replace phantom creative and governance error codes with canonical enum members sync_creatives, build_creative, the creative specification, check_governance, and sync_plans documented 13 errors[].code values that do not exist in enums/error-code.json. Remap each to the existing code with matching semantics (UNSUPPORTED_FEATURE, VALIDATION_ERROR, CREATIVE_REJECTED, INVALID_STATE, INVALID_REQUEST, PERMISSION_DENIED); replace GENERATION_FAILED with task-failure guidance per the open-vocabulary rule. Also fix the one live INVALID_FORMAT emission in the training-agent reference implementation. Same failure mode as #4852 / #5307. --- .../fix-creative-governance-phantom-error-codes.md | 5 +++++ docs/creative/specification.mdx | 7 +++---- docs/creative/task-reference/build_creative.mdx | 2 +- docs/creative/task-reference/sync_creatives.mdx | 9 ++++----- docs/governance/campaign/tasks/check_governance.mdx | 4 ++-- docs/governance/campaign/tasks/sync_plans.mdx | 4 ++-- server/src/training-agent/task-handlers.ts | 2 +- 7 files changed, 18 insertions(+), 15 deletions(-) create mode 100644 .changeset/fix-creative-governance-phantom-error-codes.md diff --git a/.changeset/fix-creative-governance-phantom-error-codes.md b/.changeset/fix-creative-governance-phantom-error-codes.md new file mode 100644 index 0000000000..3f8d8db996 --- /dev/null +++ b/.changeset/fix-creative-governance-phantom-error-codes.md @@ -0,0 +1,5 @@ +--- +"adcontextprotocol": patch +--- + +Replace phantom error codes in creative and campaign-governance task docs with canonical enum members. `sync_creatives`, `build_creative`, the Creative Protocol specification, `check_governance`, and `sync_plans` documented 13 `errors[].code` values that do not exist in `enums/error-code.json` (`INVALID_FORMAT`, `ASSET_PROCESSING_FAILED`, `BRAND_SAFETY_VIOLATION`, `FORMAT_MISMATCH`, `CREATIVE_IN_ACTIVE_DELIVERY`, `ASSET_MISSING`, `ASSET_INVALID`, `GENERATION_FAILED`, `INVALID_MANIFEST`, `AMBIGUOUS_CHECK_TYPE`, `SELLER_NOT_RECOGNIZED`, `INVALID_PLAN`, `BUDGET_BELOW_COMMITTED`). SDKs that validate `errors[].code` against the published enum reject responses built from the docs literally, the same failure mode as #4852 and #5307. Each phantom is remapped to the existing code with matching semantics (`UNSUPPORTED_FEATURE`, `VALIDATION_ERROR`, `CREATIVE_REJECTED`, `INVALID_STATE`, `INVALID_REQUEST`, `PERMISSION_DENIED`); `GENERATION_FAILED` is replaced with guidance that generation-pipeline failures surface as task-level failure with the most specific applicable canonical code, per the open-vocabulary rule on `error-code.json`. Also fixes the one live `INVALID_FORMAT` emission in the training-agent reference implementation. Docs and reference implementation only; no wire change. diff --git a/docs/creative/specification.mdx b/docs/creative/specification.mdx index 167928fd42..c862162145 100644 --- a/docs/creative/specification.mdx +++ b/docs/creative/specification.mdx @@ -394,10 +394,9 @@ Creative agents MUST return errors using the [standard AdCP error schema](/docs/ Common error codes: - `REFERENCE_NOT_FOUND`: Requested format does not exist or is not accessible (`error.field` identifies the `format_id`) -- `VALIDATION_ERROR`: Manifest failed format validation -- `ASSET_MISSING`: Required asset not provided in manifest -- `ASSET_INVALID`: Asset does not meet format constraints -- `GENERATION_FAILED`: Creative generation could not be completed +- `VALIDATION_ERROR`: Manifest failed format validation: a required asset is missing from the manifest, or an asset does not meet the format's constraints (`error.field` identifies the offending asset path) + +Generation-pipeline failures (model or rendering errors during `build_creative`) surface as task-level failure (`status: "failed"`) with the most specific applicable code in `errors[]`. The error-code vocabulary is open: sellers MAY return platform-specific codes for failure modes the canonical enum does not cover, and agents MUST handle unknown codes by falling back to the recovery classification. ## Security considerations diff --git a/docs/creative/task-reference/build_creative.mdx b/docs/creative/task-reference/build_creative.mdx index f8e92928f1..7aabf8bfc5 100644 --- a/docs/creative/task-reference/build_creative.mdx +++ b/docs/creative/task-reference/build_creative.mdx @@ -1526,6 +1526,6 @@ To refine, pass the previous response's `creative_manifest` back as input with a | Code | Description | |------|-------------| | `FORMAT_NOT_SUPPORTED` | The `target_format_id` (or `target_format_ids[N]` in a multi-format request) is not supported by this creative agent. For canonical creative-agent routing, retry with an advertised `creative.supported_formats[].capability_id`; legacy named-format IDs remain valid when the agent still advertises them. | -| `INVALID_MANIFEST` | The `creative_manifest` is malformed or missing required assets for the target format | +| `VALIDATION_ERROR` | The `creative_manifest` is malformed or missing required assets for the target format | | `CREATIVE_NOT_FOUND` | The `creative_id` does not exist in the agent's library (or in the specified `concept_id`) | | `COMPLIANCE_UNSATISFIED` | A required disclosure from the brief cannot be rendered in the target format (e.g., format does not support the required disclosure position) | diff --git a/docs/creative/task-reference/sync_creatives.mdx b/docs/creative/task-reference/sync_creatives.mdx index 701e2a2bff..f66b54273f 100644 --- a/docs/creative/task-reference/sync_creatives.mdx +++ b/docs/creative/task-reference/sync_creatives.mdx @@ -825,12 +825,11 @@ Poll `tasks/get` or wait for the webhook. The completion artifact carries the `c | Error Code | Description | Resolution | | ------------------------- | ------------------------------------------------- | -------------------------------------------------------------------- | -| `INVALID_FORMAT` | Format not supported by product | Check product's supported formats via `list_creative_formats` | -| `ASSET_PROCESSING_FAILED` | Asset file corrupt or invalid | Verify asset meets format requirements (codec, dimensions, duration) | +| `UNSUPPORTED_FEATURE` | Format not supported by this seller or product | Check product's supported formats via `list_creative_formats` | +| `VALIDATION_ERROR` | Manifest failed format validation: an asset file is corrupt or invalid, or assets don't match the format's requirements (codec, dimensions, duration). `error.field` identifies the offending asset path | Verify asset types and specifications match the format definition | | `PACKAGE_NOT_FOUND` | Package ID doesn't exist in media buy | Verify `package_id`; for legacy package correlation use `get_media_buys` + package `context.buyer_ref` | -| `BRAND_SAFETY_VIOLATION` | Creative failed brand safety scan | Review content against publisher's brand safety guidelines | -| `FORMAT_MISMATCH` | Assets don't match format requirements | Verify asset types and specifications match format definition | -| `CREATIVE_IN_ACTIVE_DELIVERY` | Creative is assigned to an active, non-paused package (blocks updates and `delete_missing` deletions) | Pause the package first, or create a new creative version | +| `CREATIVE_REJECTED` | Creative failed content policy or brand safety review | Review content against the seller's advertising policies | +| `INVALID_STATE` | Creative is assigned to an active, non-paused package (blocks updates and `delete_missing` deletions) | Pause the package first, or create a new creative version | ## Best practices diff --git a/docs/governance/campaign/tasks/check_governance.mdx b/docs/governance/campaign/tasks/check_governance.mdx index 12b39e115f..0aba76623b 100644 --- a/docs/governance/campaign/tasks/check_governance.mdx +++ b/docs/governance/campaign/tasks/check_governance.mdx @@ -478,9 +478,9 @@ The seller MUST adjust pacing and re-call `check_governance` immediately. The `n | Code | Recovery | Description | |------|----------|-------------| | `PLAN_NOT_FOUND` | correctable | No plan with this ID. The buyer may not have synced the plan yet. | -| `AMBIGUOUS_CHECK_TYPE` | correctable | Request contains both intent fields (`tool` + `payload`) and execution fields (`governance_context` + `planned_delivery`). Send one set or the other. | +| `INVALID_REQUEST` | correctable | Request contains both intent fields (`tool` + `payload`) and execution fields (`governance_context` + `planned_delivery`), so the check type cannot be inferred. Send one set or the other. | | `CAMPAIGN_SUSPENDED` | correctable | Campaign governance is suspended pending human review. | -| `SELLER_NOT_RECOGNIZED` | correctable | The caller URL is not in the plan's `approved_sellers` list. | +| `PERMISSION_DENIED` | correctable | The caller URL is not in the plan's `approved_sellers` list. | ## Related tasks diff --git a/docs/governance/campaign/tasks/sync_plans.mdx b/docs/governance/campaign/tasks/sync_plans.mdx index e2bfd60bcd..e38b619149 100644 --- a/docs/governance/campaign/tasks/sync_plans.mdx +++ b/docs/governance/campaign/tasks/sync_plans.mdx @@ -231,9 +231,9 @@ Policy categories are distinct from `brand.industries`. Industries describe what | Code | Recovery | Description | |------|----------|-------------| -| `INVALID_PLAN` | correctable | Plan is missing required fields or has invalid values. | +| `INVALID_REQUEST` | correctable | Plan is missing required fields or has invalid values. `error.field` identifies the offending plan field. | | `REFERENCE_NOT_FOUND` | correctable | Brand domain could not be resolved via the Brand Protocol. The governance agent cannot determine applicable compliance policies without a valid brand reference. `error.field` MUST identify the brand field that failed to resolve. | -| `BUDGET_BELOW_COMMITTED` | correctable | Cannot reduce budget below the amount already committed (on plan update). | +| `VALIDATION_ERROR` | correctable | Cannot reduce budget below the amount already committed (on plan update). `error.field` identifies the budget field. | ## Related tasks diff --git a/server/src/training-agent/task-handlers.ts b/server/src/training-agent/task-handlers.ts index fa2c63e383..d9eed16e34 100644 --- a/server/src/training-agent/task-handlers.ts +++ b/server/src/training-agent/task-handlers.ts @@ -7189,7 +7189,7 @@ export async function handlePreviewCreative(args: ToolArgs, ctx: TrainingContext if (!preview) { const fmtId = manifest.format_id?.id || 'unknown'; return { - errors: [{ code: 'INVALID_FORMAT', message: `Format "${fmtId}" is not supported. Use list_creative_formats to discover available formats.` }], + errors: [{ code: 'UNSUPPORTED_FEATURE', message: `Format "${fmtId}" is not supported. Use list_creative_formats to discover available formats.` }], }; }