fix(docs): replace phantom creative and governance error codes with canonical enum members#5819
Conversation
…anonical 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 adcontextprotocol#4852 / adcontextprotocol#5307.
IPR Policy Agreement Required@aleksUIX — thanks for the contribution. Before this PR can be merged, the AgenticAdvertising.Org IPR Policy requires your agreement. To agree, post a new comment on this PR with the exact phrase: Your signature is recorded once and covers all contributions to AAO repositories. See |
![aao-release-bot[bot]](https://avatars.githubusercontent.com/u/221690821?s=60&v=4){kind=small}
There was a problem hiding this comment.
Argus is not auto-reviewing this PR because it modifies protected paths that require human review (.changeset/fix-creative-governance-phantom-error-codes.md). A human reviewer should review and merge this PR; Argus will resume on subsequent PRs once these changes land on main.
|
I have read the IPR Policy |
IPR Policy — signedThanks, @aleksUIX. Your agreement to the IPR Policy is recorded at |
1 participant
Summary
sync_creatives,build_creative, the Creative Protocol specification,check_governance, andsync_plansdocument 13errors[].codevalues that do not exist instatic/schemas/source/enums/error-code.json. SDKs that validateerrors[].codeagainst the published enum reject responses built from the docs literally, and sellers reading the spec either ship a non-conformant code or invent their own. Same failure mode as #4852 (fixed in #4860) and thesync_catalogsreconciliation in #5307.Change
Each phantom is remapped to the existing canonical code whose semantics match, following the #4860 precedent of preferring existing enum members over minting new values:
sync_creatives.mdxINVALID_FORMATUNSUPPORTED_FEATURE(same mapping #4860 chose for the identical case oncreate_media_buy)sync_creatives.mdxASSET_PROCESSING_FAILED,FORMAT_MISMATCHVALIDATION_ERROR(rows merged;error.fieldidentifies the asset path)sync_creatives.mdxBRAND_SAFETY_VIOLATIONCREATIVE_REJECTEDsync_creatives.mdxCREATIVE_IN_ACTIVE_DELIVERYINVALID_STATEspecification.mdxASSET_MISSING,ASSET_INVALIDVALIDATION_ERRORbulletspecification.mdxGENERATION_FAILEDerror-code.jsonbuild_creative.mdxINVALID_MANIFESTVALIDATION_ERRORcheck_governance.mdxAMBIGUOUS_CHECK_TYPEINVALID_REQUESTcheck_governance.mdxSELLER_NOT_RECOGNIZEDPERMISSION_DENIEDsync_plans.mdxINVALID_PLANINVALID_REQUESTsync_plans.mdxBUDGET_BELOW_COMMITTEDVALIDATION_ERRORAlso fixes the one live emission: the training-agent reference implementation returned
INVALID_FORMATfrom its preview handler (server/src/training-agent/task-handlers.ts), nowUNSUPPORTED_FEATURE.If the working group would rather mint dedicated codes for any of these (the governance pair in particular), happy to rework against the enum-membership criterion in
docs/spec-guidelines.md; this PR takes the conservative docs-only path so no wire change is involved.Files
docs/creative/task-reference/sync_creatives.mdx,docs/creative/specification.mdx,docs/creative/task-reference/build_creative.mdxdocs/governance/campaign/tasks/check_governance.mdx,docs/governance/campaign/tasks/sync_plans.mdxserver/src/training-agent/task-handlers.ts.changeset/fix-creative-governance-phantom-error-codes.md(patch)Verification
scripts/lint-error-codes.cjsclean;scripts/lint-error-code-drift.cjsclean (no enum change)scripts/check-changeset-protocol-scope.cjs origin/mainpassescanonical-reference-resolver.test.cjsand 3 unit tests) reproduce identically on cleanmain, so they are environment issues unrelated to this change