enums/error-code.json missing INVALID_PRICING_OPTION (and possibly INVALID_USAGE_DATA, DUPLICATE_REQUEST) used in report_usage docs

[MichielDean]

Summary

INVALID_PRICING_OPTION is used in the official report_usage documentation — both in an example JSON response and in the error-handling table — but is absent from the canonical enums/error-code.json enum.

Evidence

Used in docs (docs/accounts/tasks/report_usage.mdx):

{
  "accepted": 1,
  "errors": [
    {
      "code": "INVALID_PRICING_OPTION",
      "message": "pricing_option_id 'po_unknown' does not exist on this account",
      "field": "usage[1].pricing_option_id"
    }
  ]
}

Also referenced in the error table:
| INVALID_PRICING_OPTION | pricing_option_id not found on this account | Verify pricing_option_id from the vendor's discovery response |

Missing from: enums/error-code.json (verified against current v3 schema — the code does not appear in the enum array)

Additional codes to check

The same report_usage error table also references INVALID_USAGE_DATA and DUPLICATE_REQUEST, which may also be missing from the enum. These should be audited at the same time.

Impact

• Schema validation against enums/error-code.json will reject INVALID_PRICING_OPTION as an unknown code, despite it being a documented standard code.
• Implementations following the docs are using a code that technically fails strict enum validation.

Fix

Add INVALID_PRICING_OPTION (and INVALID_USAGE_DATA, DUPLICATE_REQUEST if confirmed missing) to enums/error-code.json with appropriate descriptions and recovery classifications, consistent with their usage in report_usage.mdx.

Labels suggestion

bug, schema, accounts

[bokelley]

Triage

Classification: Bug
Bucket(s): spec / protocol
Status: ready-to-implement

What the experts said:

• ad-tech-protocol-expert: INVALID_PRICING_OPTION and INVALID_USAGE_DATA are sound, distinct additions (prior art: BILLING_OUT_OF_BAND, ITEM_VALIDATION_FAILED). DUPLICATE_REQUEST violates the idempotency transparency invariant — successful replay must return the original response unchanged, so no advisory code can appear in it. Also flags core/error.json line 84 using INVALID_PRICING_MODEL in its canonical example — required alignment in the same PR.
• adtech-product-expert: No runtime breakage (spec's unknown-code fallback applies), but SDK codegen treats undeclared codes as untyped on a billing-critical surface. DUPLICATE_REQUEST is semantically confused; fix docs, not schema. Both valid codes are 3.1-track only.

My take: Experts converge cleanly. Add two codes, fix one doc row. The error.json naming conflict is a required companion fix — INVALID_PRICING_MODEL alongside the incoming INVALID_PRICING_OPTION is a second doc-schema conflict in the same billing path.

Implementation scope:

• static/schemas/source/enums/error-code.json — append INVALID_PRICING_OPTION and INVALID_USAGE_DATA to enum[], enumDescriptions, and enumMetadata (both: recovery: correctable)
• static/schemas/source/core/error.json — fix line 84 example: INVALID_PRICING_MODEL → INVALID_PRICING_OPTION
• docs/accounts/tasks/report_usage.mdx — remove DUPLICATE_REQUEST from error table; add Retry Safety prose: idempotent replays return the original response transparently with no advisory code emitted
• Non-breaking (appended enum values; error.code is open string); changeset: minor; base: main

---

Triaged by Claude Code. Session: https://claude.ai/code/session_016r6s5VS7ftBrFh1qsdm2V1

---

Generated by Claude Code

[bokelley]

Lineage decision: adding canonical error codes changes the protocol enum surface, so this is 3.2.0 work rather than a 3.1.x patch. The 3.2 change must reconcile every code used by report_usage prose/examples against the canonical enum in one sweep.