@adcp/sdk 12.0.6 → 12.1.0

package/dist/lib/types/error-codes.d.mts

@@ -290,9 +290,9 @@ export declare const STANDARD_ERROR_CODES: {
         readonly suggestion: "perform a natural-key check to determine whether the original request succeeded; if no evidence of success, generate a fresh idempotency_key for a new attempt";
     };
     IDEMPOTENCY_IN_FLIGHT: {
-        readonly description: "A prior request with the same `idempotency_key` is still being processed and has not yet produced a cached response. The second request arrived before the first completed. Sellers MAY return this code instead of blocking the second caller until the first finishes — useful when the first call invokes a slow downstream system (SSP, ad server, payment provider). Distinct from IDEMPOTENCY_CONFLICT (different canonical payload — a client bug) and from CONFLICT (concurrent modification of a different resource) — IDEMPOTENCY_IN_FLIGHT is the seller telling the buyer 'your retry was correct but your previous attempt is still running, come back shortly.' Sellers SHOULD populate `error.details.retry_after` (seconds, integer) with a wait hint based on the first request's elapsed time and expected completion. Buyers MUST treat this as transient and MUST NOT mint a fresh `idempotency_key` — minting a new key turns a safe retry into a double-execution race.";
+        readonly description: "A prior request with the same `idempotency_key` is still being processed and has not yet produced a cached response. The second request arrived before the first completed. Sellers MAY return this code instead of blocking the second caller until the first finishes — useful when the first call invokes a slow downstream system (SSP, ad server, payment provider). Distinct from IDEMPOTENCY_CONFLICT (different canonical payload — a client bug) and from CONFLICT (concurrent modification of a different resource) — IDEMPOTENCY_IN_FLIGHT is the seller telling the buyer 'your retry was correct but your previous attempt is still running, come back shortly.' Sellers SHOULD populate top-level `error.retry_after` (seconds) with a wait hint based on the first request's elapsed time and expected completion. Buyers MUST treat this as transient and MUST NOT mint a fresh `idempotency_key` — minting a new key turns a safe retry into a double-execution race.";
         readonly recovery: "transient";
-        readonly suggestion: "wait error.details.retry_after seconds and retry with the SAME idempotency_key — MUST NOT mint a fresh key (turns a safe retry into a double-execution race)";
+        readonly suggestion: "wait top-level error.retry_after seconds and retry with the SAME idempotency_key — MUST NOT mint a fresh key (turns a safe retry into a double-execution race)";
     };
     INVALID_FEED_FORMAT: {
         readonly description: "Catalog feed content does not match the declared feed_format.";
@@ -435,9 +435,9 @@ export declare const STANDARD_ERROR_CODES: {
         readonly suggestion: "replace verify_agent.agent_url with one from the seller's published accepted_verifiers, drop verify_agent if the embedding is self-verifiable, or re-embed with a verifier the seller accepts";
     };
     RATE_LIMITED: {
-        readonly description: "Request rate exceeded. Retry after the retry_after interval.";
+        readonly description: "Request rate exceeded. Sellers SHOULD populate top-level `error.retry_after` with the number of seconds to wait.";
         readonly recovery: "transient";
-        readonly suggestion: "retry after the retry_after interval";
+        readonly suggestion: "wait top-level error.retry_after seconds when present, then retry";
     };
     READ_ONLY_SCOPE: {
         readonly description: "The caller's scope is read-only; the invoked task would mutate state and was rejected. Distinct from `SCOPE_INSUFFICIENT` (task not in scope at all) — the task is in some scopes this seller supports, just not this caller's.";

package/dist/lib/types/error-codes.d.ts

@@ -290,9 +290,9 @@ export declare const STANDARD_ERROR_CODES: {
         readonly suggestion: "perform a natural-key check to determine whether the original request succeeded; if no evidence of success, generate a fresh idempotency_key for a new attempt";
     };
     IDEMPOTENCY_IN_FLIGHT: {
-        readonly description: "A prior request with the same `idempotency_key` is still being processed and has not yet produced a cached response. The second request arrived before the first completed. Sellers MAY return this code instead of blocking the second caller until the first finishes — useful when the first call invokes a slow downstream system (SSP, ad server, payment provider). Distinct from IDEMPOTENCY_CONFLICT (different canonical payload — a client bug) and from CONFLICT (concurrent modification of a different resource) — IDEMPOTENCY_IN_FLIGHT is the seller telling the buyer 'your retry was correct but your previous attempt is still running, come back shortly.' Sellers SHOULD populate `error.details.retry_after` (seconds, integer) with a wait hint based on the first request's elapsed time and expected completion. Buyers MUST treat this as transient and MUST NOT mint a fresh `idempotency_key` — minting a new key turns a safe retry into a double-execution race.";
+        readonly description: "A prior request with the same `idempotency_key` is still being processed and has not yet produced a cached response. The second request arrived before the first completed. Sellers MAY return this code instead of blocking the second caller until the first finishes — useful when the first call invokes a slow downstream system (SSP, ad server, payment provider). Distinct from IDEMPOTENCY_CONFLICT (different canonical payload — a client bug) and from CONFLICT (concurrent modification of a different resource) — IDEMPOTENCY_IN_FLIGHT is the seller telling the buyer 'your retry was correct but your previous attempt is still running, come back shortly.' Sellers SHOULD populate top-level `error.retry_after` (seconds) with a wait hint based on the first request's elapsed time and expected completion. Buyers MUST treat this as transient and MUST NOT mint a fresh `idempotency_key` — minting a new key turns a safe retry into a double-execution race.";
         readonly recovery: "transient";
-        readonly suggestion: "wait error.details.retry_after seconds and retry with the SAME idempotency_key — MUST NOT mint a fresh key (turns a safe retry into a double-execution race)";
+        readonly suggestion: "wait top-level error.retry_after seconds and retry with the SAME idempotency_key — MUST NOT mint a fresh key (turns a safe retry into a double-execution race)";
     };
     INVALID_FEED_FORMAT: {
         readonly description: "Catalog feed content does not match the declared feed_format.";
@@ -435,9 +435,9 @@ export declare const STANDARD_ERROR_CODES: {
         readonly suggestion: "replace verify_agent.agent_url with one from the seller's published accepted_verifiers, drop verify_agent if the embedding is self-verifiable, or re-embed with a verifier the seller accepts";
     };
     RATE_LIMITED: {
-        readonly description: "Request rate exceeded. Retry after the retry_after interval.";
+        readonly description: "Request rate exceeded. Sellers SHOULD populate top-level `error.retry_after` with the number of seconds to wait.";
         readonly recovery: "transient";
-        readonly suggestion: "retry after the retry_after interval";
+        readonly suggestion: "wait top-level error.retry_after seconds when present, then retry";
     };
     READ_ONLY_SCOPE: {
         readonly description: "The caller's scope is read-only; the invoked task would mutate state and was rejected. Distinct from `SCOPE_INSUFFICIENT` (task not in scope at all) — the task is in some scopes this seller supports, just not this caller's.";

package/dist/lib/types/get-adcp-capabilities.d.ts

@@ -2733,7 +2733,7 @@ export interface IdempotencySupported {
      */
     replay_ttl_seconds: number;
     /**
-     * Maximum lifetime in seconds of an in-flight idempotency row before the seller releases it per L1/security.mdx rule 9 (treat the in-flight attempt as failed if the handler does not complete within this bound). Buyer SDKs use this value to compute a retry budget when they see `IDEMPOTENCY_IN_FLIGHT` — cap individual retry waits at this value rather than the much-wider `replay_ttl_seconds` ceiling. Optional in 3.1 (additive declaration); SDKs that don't see the field fall back to rule 9's order-of-magnitude SHOULD heuristic. Required when `supported: true` in 4.0. MUST be no greater than `replay_ttl_seconds` (a bound larger than the replay window is vacuous — any retry past the TTL hits IDEMPOTENCY_EXPIRED regardless of in-flight state); validators MUST enforce this cross-field constraint at the test layer since JSON Schema cannot express field-relative bounds. A buyer that observes `error.details.retry_after` exceeding this value MAY treat that as a seller bug — the in-flight row cannot legitimately outlive the bound the seller declared.
+     * Maximum lifetime in seconds of an in-flight idempotency row before the seller releases it per L1/security.mdx rule 9 (treat the in-flight attempt as failed if the handler does not complete within this bound). Buyer SDKs use this value to compute a retry budget when they see `IDEMPOTENCY_IN_FLIGHT` — cap individual retry waits at this value rather than the much-wider `replay_ttl_seconds` ceiling. Optional in 3.1 (additive declaration); SDKs that don't see the field fall back to rule 9's order-of-magnitude SHOULD heuristic. Required when `supported: true` in 4.0. MUST be no greater than `replay_ttl_seconds` (a bound larger than the replay window is vacuous — any retry past the TTL hits IDEMPOTENCY_EXPIRED regardless of in-flight state); validators MUST enforce this cross-field constraint at the test layer since JSON Schema cannot express field-relative bounds. A buyer that observes top-level `error.retry_after` exceeding this value MAY treat that as a seller bug — the in-flight row cannot legitimately outlive the bound the seller declared.
      * @minimum 1
      * @maximum 604800
      */

package/dist/lib/types/get-products.d.ts

@@ -848,7 +848,55 @@ export interface CancellationPolicy {
         /**
          * Fee calculation method. 'percent_remaining': percentage of remaining uncommitted spend. 'full_commitment': buyer owes the full committed budget regardless of delivery. 'fixed_fee': flat monetary amount. 'none': no financial fee (cancellation with notice is free).
          */
-        type: 'percent_remaining' | 'full_commitment' | 'fixed_fee' | 'none';
+        type: 'percent_remaining';
+        /**
+         * Fee rate as a decimal proportion of remaining committed spend. Required when type is 'percent_remaining' (e.g., 0.5 means 50% of remaining spend).
+         * @minimum 0
+         * @maximum 1
+         */
+        rate: number;
+        /**
+         * Fixed fee amount in the buy's currency. Required when type is 'fixed_fee'.
+         * @minimum 0
+         */
+        amount?: number;
+    } | {
+        /**
+         * Fee calculation method. 'percent_remaining': percentage of remaining uncommitted spend. 'full_commitment': buyer owes the full committed budget regardless of delivery. 'fixed_fee': flat monetary amount. 'none': no financial fee (cancellation with notice is free).
+         */
+        type: 'full_commitment';
+        /**
+         * Fee rate as a decimal proportion of remaining committed spend. Required when type is 'percent_remaining' (e.g., 0.5 means 50% of remaining spend).
+         * @minimum 0
+         * @maximum 1
+         */
+        rate?: number;
+        /**
+         * Fixed fee amount in the buy's currency. Required when type is 'fixed_fee'.
+         * @minimum 0
+         */
+        amount?: number;
+    } | {
+        /**
+         * Fee calculation method. 'percent_remaining': percentage of remaining uncommitted spend. 'full_commitment': buyer owes the full committed budget regardless of delivery. 'fixed_fee': flat monetary amount. 'none': no financial fee (cancellation with notice is free).
+         */
+        type: 'fixed_fee';
+        /**
+         * Fee rate as a decimal proportion of remaining committed spend. Required when type is 'percent_remaining' (e.g., 0.5 means 50% of remaining spend).
+         * @minimum 0
+         * @maximum 1
+         */
+        rate?: number;
+        /**
+         * Fixed fee amount in the buy's currency. Required when type is 'fixed_fee'.
+         * @minimum 0
+         */
+        amount: number;
+    } | {
+        /**
+         * Fee calculation method. 'percent_remaining': percentage of remaining uncommitted spend. 'full_commitment': buyer owes the full committed budget regardless of delivery. 'fixed_fee': flat monetary amount. 'none': no financial fee (cancellation with notice is free).
+         */
+        type: 'none';
         /**
          * Fee rate as a decimal proportion of remaining committed spend. Required when type is 'percent_remaining' (e.g., 0.5 means 50% of remaining spend).
          * @minimum 0

package/dist/lib/types/get-task-status.d.ts

@@ -1811,7 +1811,55 @@ export interface CancellationPolicy {
         /**
          * Fee calculation method. 'percent_remaining': percentage of remaining uncommitted spend. 'full_commitment': buyer owes the full committed budget regardless of delivery. 'fixed_fee': flat monetary amount. 'none': no financial fee (cancellation with notice is free).
          */
-        type: 'percent_remaining' | 'full_commitment' | 'fixed_fee' | 'none';
+        type: 'percent_remaining';
+        /**
+         * Fee rate as a decimal proportion of remaining committed spend. Required when type is 'percent_remaining' (e.g., 0.5 means 50% of remaining spend).
+         * @minimum 0
+         * @maximum 1
+         */
+        rate: number;
+        /**
+         * Fixed fee amount in the buy's currency. Required when type is 'fixed_fee'.
+         * @minimum 0
+         */
+        amount?: number;
+    } | {
+        /**
+         * Fee calculation method. 'percent_remaining': percentage of remaining uncommitted spend. 'full_commitment': buyer owes the full committed budget regardless of delivery. 'fixed_fee': flat monetary amount. 'none': no financial fee (cancellation with notice is free).
+         */
+        type: 'full_commitment';
+        /**
+         * Fee rate as a decimal proportion of remaining committed spend. Required when type is 'percent_remaining' (e.g., 0.5 means 50% of remaining spend).
+         * @minimum 0
+         * @maximum 1
+         */
+        rate?: number;
+        /**
+         * Fixed fee amount in the buy's currency. Required when type is 'fixed_fee'.
+         * @minimum 0
+         */
+        amount?: number;
+    } | {
+        /**
+         * Fee calculation method. 'percent_remaining': percentage of remaining uncommitted spend. 'full_commitment': buyer owes the full committed budget regardless of delivery. 'fixed_fee': flat monetary amount. 'none': no financial fee (cancellation with notice is free).
+         */
+        type: 'fixed_fee';
+        /**
+         * Fee rate as a decimal proportion of remaining committed spend. Required when type is 'percent_remaining' (e.g., 0.5 means 50% of remaining spend).
+         * @minimum 0
+         * @maximum 1
+         */
+        rate?: number;
+        /**
+         * Fixed fee amount in the buy's currency. Required when type is 'fixed_fee'.
+         * @minimum 0
+         */
+        amount: number;
+    } | {
+        /**
+         * Fee calculation method. 'percent_remaining': percentage of remaining uncommitted spend. 'full_commitment': buyer owes the full committed budget regardless of delivery. 'fixed_fee': flat monetary amount. 'none': no financial fee (cancellation with notice is free).
+         */
+        type: 'none';
         /**
          * Fee rate as a decimal proportion of remaining committed spend. Required when type is 'percent_remaining' (e.g., 0.5 means 50% of remaining spend).
          * @minimum 0

package/dist/lib/types/manifest.generated.d.mts

@@ -1,5 +1,5 @@
 /**
- * Manifest-derived constants for AdCP 3.1.2.
+ * Manifest-derived constants for AdCP 3.1.5.
  *
  * Single source of truth for tool↔protocol grouping, error-code metadata
  * (description + recovery + suggestion), and specialism→required-tools
@@ -9,8 +9,8 @@
  * previously lived in `src/lib/utils/capabilities.ts` and
  * `src/lib/types/error-codes.ts`.
  *
- * Source: `schemas/cache/3.1.2/manifest.json` (adcp_version: 3.1.2, generated_at:
- * 2026-07-08T13:55:47.979Z). Re-run `npm run sync-schemas` then
+ * Source: `schemas/cache/3.1.5/manifest.json` (adcp_version: 3.1.5, generated_at:
+ * 2026-07-24T14:33:01.323Z). Re-run `npm run sync-schemas` then
  * `npm run generate-manifest-derived` to refresh after a spec bump.
  */
 export type ErrorRecovery = 'transient' | 'correctable' | 'terminal';
@@ -262,9 +262,9 @@ export declare const STANDARD_ERROR_CODES_FROM_MANIFEST: {
         readonly suggestion: "perform a natural-key check to determine whether the original request succeeded; if no evidence of success, generate a fresh idempotency_key for a new attempt";
     };
     readonly IDEMPOTENCY_IN_FLIGHT: {
-        readonly description: "A prior request with the same `idempotency_key` is still being processed and has not yet produced a cached response. The second request arrived before the first completed. Sellers MAY return this code instead of blocking the second caller until the first finishes — useful when the first call invokes a slow downstream system (SSP, ad server, payment provider). Distinct from IDEMPOTENCY_CONFLICT (different canonical payload — a client bug) and from CONFLICT (concurrent modification of a different resource) — IDEMPOTENCY_IN_FLIGHT is the seller telling the buyer 'your retry was correct but your previous attempt is still running, come back shortly.' Sellers SHOULD populate `error.details.retry_after` (seconds, integer) with a wait hint based on the first request's elapsed time and expected completion. Buyers MUST treat this as transient and MUST NOT mint a fresh `idempotency_key` — minting a new key turns a safe retry into a double-execution race.";
+        readonly description: "A prior request with the same `idempotency_key` is still being processed and has not yet produced a cached response. The second request arrived before the first completed. Sellers MAY return this code instead of blocking the second caller until the first finishes — useful when the first call invokes a slow downstream system (SSP, ad server, payment provider). Distinct from IDEMPOTENCY_CONFLICT (different canonical payload — a client bug) and from CONFLICT (concurrent modification of a different resource) — IDEMPOTENCY_IN_FLIGHT is the seller telling the buyer 'your retry was correct but your previous attempt is still running, come back shortly.' Sellers SHOULD populate top-level `error.retry_after` (seconds) with a wait hint based on the first request's elapsed time and expected completion. Buyers MUST treat this as transient and MUST NOT mint a fresh `idempotency_key` — minting a new key turns a safe retry into a double-execution race.";
         readonly recovery: "transient";
-        readonly suggestion: "wait error.details.retry_after seconds and retry with the SAME idempotency_key — MUST NOT mint a fresh key (turns a safe retry into a double-execution race)";
+        readonly suggestion: "wait top-level error.retry_after seconds and retry with the SAME idempotency_key — MUST NOT mint a fresh key (turns a safe retry into a double-execution race)";
     };
     readonly INVALID_FEED_FORMAT: {
         readonly description: "Catalog feed content does not match the declared feed_format.";
@@ -407,9 +407,9 @@ export declare const STANDARD_ERROR_CODES_FROM_MANIFEST: {
         readonly suggestion: "replace verify_agent.agent_url with one from the seller's published accepted_verifiers, drop verify_agent if the embedding is self-verifiable, or re-embed with a verifier the seller accepts";
     };
     readonly RATE_LIMITED: {
-        readonly description: "Request rate exceeded. Retry after the retry_after interval.";
+        readonly description: "Request rate exceeded. Sellers SHOULD populate top-level `error.retry_after` with the number of seconds to wait.";
         readonly recovery: "transient";
-        readonly suggestion: "retry after the retry_after interval";
+        readonly suggestion: "wait top-level error.retry_after seconds when present, then retry";
     };
     readonly READ_ONLY_SCOPE: {
         readonly description: "The caller's scope is read-only; the invoked task would mutate state and was rejected. Distinct from `SCOPE_INSUFFICIENT` (task not in scope at all) — the task is in some scopes this seller supports, just not this caller's.";

package/dist/lib/types/manifest.generated.d.ts

@@ -1,5 +1,5 @@
 /**
- * Manifest-derived constants for AdCP 3.1.2.
+ * Manifest-derived constants for AdCP 3.1.5.
  *
  * Single source of truth for tool↔protocol grouping, error-code metadata
  * (description + recovery + suggestion), and specialism→required-tools
@@ -9,8 +9,8 @@
  * previously lived in `src/lib/utils/capabilities.ts` and
  * `src/lib/types/error-codes.ts`.
  *
- * Source: `schemas/cache/3.1.2/manifest.json` (adcp_version: 3.1.2, generated_at:
- * 2026-07-08T13:55:47.979Z). Re-run `npm run sync-schemas` then
+ * Source: `schemas/cache/3.1.5/manifest.json` (adcp_version: 3.1.5, generated_at:
+ * 2026-07-24T14:33:01.323Z). Re-run `npm run sync-schemas` then
  * `npm run generate-manifest-derived` to refresh after a spec bump.
  */
 export type ErrorRecovery = 'transient' | 'correctable' | 'terminal';
@@ -262,9 +262,9 @@ export declare const STANDARD_ERROR_CODES_FROM_MANIFEST: {
         readonly suggestion: "perform a natural-key check to determine whether the original request succeeded; if no evidence of success, generate a fresh idempotency_key for a new attempt";
     };
     readonly IDEMPOTENCY_IN_FLIGHT: {
-        readonly description: "A prior request with the same `idempotency_key` is still being processed and has not yet produced a cached response. The second request arrived before the first completed. Sellers MAY return this code instead of blocking the second caller until the first finishes — useful when the first call invokes a slow downstream system (SSP, ad server, payment provider). Distinct from IDEMPOTENCY_CONFLICT (different canonical payload — a client bug) and from CONFLICT (concurrent modification of a different resource) — IDEMPOTENCY_IN_FLIGHT is the seller telling the buyer 'your retry was correct but your previous attempt is still running, come back shortly.' Sellers SHOULD populate `error.details.retry_after` (seconds, integer) with a wait hint based on the first request's elapsed time and expected completion. Buyers MUST treat this as transient and MUST NOT mint a fresh `idempotency_key` — minting a new key turns a safe retry into a double-execution race.";
+        readonly description: "A prior request with the same `idempotency_key` is still being processed and has not yet produced a cached response. The second request arrived before the first completed. Sellers MAY return this code instead of blocking the second caller until the first finishes — useful when the first call invokes a slow downstream system (SSP, ad server, payment provider). Distinct from IDEMPOTENCY_CONFLICT (different canonical payload — a client bug) and from CONFLICT (concurrent modification of a different resource) — IDEMPOTENCY_IN_FLIGHT is the seller telling the buyer 'your retry was correct but your previous attempt is still running, come back shortly.' Sellers SHOULD populate top-level `error.retry_after` (seconds) with a wait hint based on the first request's elapsed time and expected completion. Buyers MUST treat this as transient and MUST NOT mint a fresh `idempotency_key` — minting a new key turns a safe retry into a double-execution race.";
         readonly recovery: "transient";
-        readonly suggestion: "wait error.details.retry_after seconds and retry with the SAME idempotency_key — MUST NOT mint a fresh key (turns a safe retry into a double-execution race)";
+        readonly suggestion: "wait top-level error.retry_after seconds and retry with the SAME idempotency_key — MUST NOT mint a fresh key (turns a safe retry into a double-execution race)";
     };
     readonly INVALID_FEED_FORMAT: {
         readonly description: "Catalog feed content does not match the declared feed_format.";
@@ -407,9 +407,9 @@ export declare const STANDARD_ERROR_CODES_FROM_MANIFEST: {
         readonly suggestion: "replace verify_agent.agent_url with one from the seller's published accepted_verifiers, drop verify_agent if the embedding is self-verifiable, or re-embed with a verifier the seller accepts";
     };
     readonly RATE_LIMITED: {
-        readonly description: "Request rate exceeded. Retry after the retry_after interval.";
+        readonly description: "Request rate exceeded. Sellers SHOULD populate top-level `error.retry_after` with the number of seconds to wait.";
         readonly recovery: "transient";
-        readonly suggestion: "retry after the retry_after interval";
+        readonly suggestion: "wait top-level error.retry_after seconds when present, then retry";
     };
     readonly READ_ONLY_SCOPE: {
         readonly description: "The caller's scope is read-only; the invoked task would mutate state and was rejected. Distinct from `SCOPE_INSUFFICIENT` (task not in scope at all) — the task is in some scopes this seller supports, just not this caller's.";

package/dist/lib/types/manifest.generated.js

@@ -263,9 +263,9 @@ const STANDARD_ERROR_CODES_FROM_MANIFEST = {
     suggestion: "perform a natural-key check to determine whether the original request succeeded; if no evidence of success, generate a fresh idempotency_key for a new attempt"
   },
   IDEMPOTENCY_IN_FLIGHT: {
-    description: "A prior request with the same `idempotency_key` is still being processed and has not yet produced a cached response. The second request arrived before the first completed. Sellers MAY return this code instead of blocking the second caller until the first finishes \u2014 useful when the first call invokes a slow downstream system (SSP, ad server, payment provider). Distinct from IDEMPOTENCY_CONFLICT (different canonical payload \u2014 a client bug) and from CONFLICT (concurrent modification of a different resource) \u2014 IDEMPOTENCY_IN_FLIGHT is the seller telling the buyer 'your retry was correct but your previous attempt is still running, come back shortly.' Sellers SHOULD populate `error.details.retry_after` (seconds, integer) with a wait hint based on the first request's elapsed time and expected completion. Buyers MUST treat this as transient and MUST NOT mint a fresh `idempotency_key` \u2014 minting a new key turns a safe retry into a double-execution race.",
+    description: "A prior request with the same `idempotency_key` is still being processed and has not yet produced a cached response. The second request arrived before the first completed. Sellers MAY return this code instead of blocking the second caller until the first finishes \u2014 useful when the first call invokes a slow downstream system (SSP, ad server, payment provider). Distinct from IDEMPOTENCY_CONFLICT (different canonical payload \u2014 a client bug) and from CONFLICT (concurrent modification of a different resource) \u2014 IDEMPOTENCY_IN_FLIGHT is the seller telling the buyer 'your retry was correct but your previous attempt is still running, come back shortly.' Sellers SHOULD populate top-level `error.retry_after` (seconds) with a wait hint based on the first request's elapsed time and expected completion. Buyers MUST treat this as transient and MUST NOT mint a fresh `idempotency_key` \u2014 minting a new key turns a safe retry into a double-execution race.",
     recovery: "transient",
-    suggestion: "wait error.details.retry_after seconds and retry with the SAME idempotency_key \u2014 MUST NOT mint a fresh key (turns a safe retry into a double-execution race)"
+    suggestion: "wait top-level error.retry_after seconds and retry with the SAME idempotency_key \u2014 MUST NOT mint a fresh key (turns a safe retry into a double-execution race)"
   },
   INVALID_FEED_FORMAT: {
     description: "Catalog feed content does not match the declared feed_format.",
@@ -408,9 +408,9 @@ const STANDARD_ERROR_CODES_FROM_MANIFEST = {
     suggestion: "replace verify_agent.agent_url with one from the seller's published accepted_verifiers, drop verify_agent if the embedding is self-verifiable, or re-embed with a verifier the seller accepts"
   },
   RATE_LIMITED: {
-    description: "Request rate exceeded. Retry after the retry_after interval.",
+    description: "Request rate exceeded. Sellers SHOULD populate top-level `error.retry_after` with the number of seconds to wait.",
     recovery: "transient",
-    suggestion: "retry after the retry_after interval"
+    suggestion: "wait top-level error.retry_after seconds when present, then retry"
   },
   READ_ONLY_SCOPE: {
     description: "The caller's scope is read-only; the invoked task would mutate state and was rejected. Distinct from `SCOPE_INSUFFICIENT` (task not in scope at all) \u2014 the task is in some scopes this seller supports, just not this caller's.",