Skip to content
Skills Library
Programming · Learning & explanation

acp-dev-patterns

/acp-dev-patterns

Cross-cutting ACP development patterns — idempotency, error handling, 3D Secure flows, request signing, rate limiting, monitoring, and security best practices. Use when designing architecture or solving production concerns.

Licence
MIT
Last repository change
14.09.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
2
Deprecation

No signals detected. Repository changed on 14.09.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

Cross-cutting ACP development patterns — idempotency, error handling, 3D Secure flows, request signing, rate limiting, monitoring, and security best practices. Use when designing architecture or solving production concerns.

Original author description

Cross-cutting ACP development patterns — idempotency, error handling, 3D Secure flows, request signing, rate limiting, monitoring, and security best practices. Use when designing architecture or solving production concerns.

How it works

  1. Before writing code
  2. Pattern: Idempotency
  3. Pattern: Error Handling
  4. Pattern: 3D Secure Authentication
  5. Pattern: Request Signing
  6. Pattern: Webhook Delivery
  7. Pattern: API Versioning
  8. Pattern: Rate Limiting
  9. Pattern: Monetary Amount Safety
  10. Pattern: Monitoring & Observability
Original SKILL.md headings · 128 lines, 660 words
SKILL.md preview
---
name: acp-dev-patterns
description: Cross-cutting ACP development patterns — idempotency, error handling, 3D Secure flows, request signing, rate limiting, monitoring, and security best practices. Use when designing architecture or solving production concerns.
allowed-tools: Read, Write, Edit, Bash, Grep, Glob, WebSearch, WebFetch
---

# ACP Development Patterns

## Before writing code

**Fetch live docs**:
- Checkout spec: Fetch `https://developers.openai.com/commerce/specs/checkout/` for error codes and idempotency rules
- Production guide: Fetch `https://developers.openai.com/commerce/guides/production/` for operational requirements
- Stripe integration: Web-search `site:docs.stripe.com agentic-commerce` for PSP-side patterns
- Changelog: Web-search `site:github.com agentic-commerce-protocol CHANGELOG` for latest changes

## Pattern: Idempotency

Every POST request MUST include `Idempotency-Key` (UUID v4, max 255 chars).

**Server-side implementation**:
- Store key → response mapping for minimum 24 hours
- Same key + identical body = replay original response, add `Idempotent-Replayed: true` header
- Same key + different body = 422 `idempotency_conflict`
- Key in flight = 409 `idempotency_in_flight` with `Retry-After` header
- 5xx responses are NOT cached — retries treated as fresh requests

**Client-side implementation**:
- Generate UUID v4 for each logical operation
- Reuse the same key when retrying a failed request
- Generate a new key for a genuinely new operation
- Handle 409 by waiting per `Retry-After` then retrying

## Pattern: Error Handling

ACP uses a flat error structure:
```
{type, code, message, param}
```

- `type`: `invalid_request` | `processing_error` | `service_unavailable`
- `code`: Well-known identifier (e.g., `idempotency_conflict`, `invalid_card`, `rate_limit_exceeded`)
- `message`: Human-readable description
- `param`: JSONPath (RFC 9535) to the offending field

**Retry strategy**:
- `429 rate_limit_exceeded` — Exponential backoff with jitter
- `409 idempotency_in_flight` — Wait per `Retry-After` header
- `5xx` — Retry with same idempotency key, exponential backoff
- `4xx` (except 429) — Do not retry, fix the request

## Pattern: 3D Secure Authentication

When `complete` returns `authentication_required`:

1. Extract 3DS challenge from the response
2. Present challenge to the buyer (redirect or modal)
3. Buyer completes authentication
4. Call `complete` again with `authentication_result`:
   - `three_ds_cryptogram`
   - `electronic_commerce_indicator`
   - `transaction_id`
   - `version`
5. Merchant processes the authenticated payment

Handle authentication timeouts and failures gracefully.

## Pattern: Request Signing

For request integrity verification:
- **Signature header**: Base64-encoded signature over canonical JSON body
- **Timestamp header**: RFC 3339 for freshness validation
- **Algorithm**: HMAC (Base64-encoded HMAC signature over canonical JSON body)
- **Verification**: Reconstruct canonical JSON, verify signature, check timestamp within clock-skew window

## Pattern: Webhook Delivery

Merchant → Agent webhook best practices:
- Sign EVERY event with HMAC-SHA256
- Include event ID for consumer-side deduplication
- Implement exponential backoff for failed deliveries
- Set reasonable timeouts (5-30 seconds)
- Log delivery attempts and responses
- Queue events if the webhook endpoint is down
- Verify the receiving endpoint uses HTTPS

## Pattern: API Versioning

- Always send `API-Version: YYYY-MM-DD` header
- Pin to a specific version in your code
- Test against new versions before upgrading
- Handle version-specific response shape differences
- Log the version used for debugging

## Pattern: Rate Limiting

- Implement server-side rate limiting per API key
- Return 429 with `Retry-After` header when exceeded
- Client-side: Honor `Retry-After`, add jitter to prevent thundering herd
- Monitor rate limit proximity and alert before hitting limits

## Pattern: Monetary Amount Safety

- ALL amounts as integers in minor currency units
- `$19.99` = `1999` (cents)
- Never use floating-point for money
- Validate on input and output
- Use language-specific money libraries (e.g., `decimal` in Python, `BigInt` in JS)

## Pattern: Monitoring & Observability

- Log every checkout operation with session ID and status
- Track conversion funnel: create → update → complete → order
- Alert on error rate spikes (especially 5xx)
- Monitor idempotency key reuse patterns
- Track payment success/failure rates
- Dashboard SPT provisioning and consumption
- Monitor webhook delivery success rates

## Pattern: Security Checklist

- TLS 1.2+ on all endpoints
- Bearer token rotation strategy
- No PCI data in logs (redact card numbers, CVCs)
- IP allowlisting for agent platform connections
- Request signing for integrity verification
- HMAC verification on all incoming webhooks
- Rate limiting to prevent abuse
- Input validation on all fields
- CORS configuration (if browser-facing)

Fetch the latest spec and production guide for current error codes, header requirements, and security recommendations before implementing.

Versions

The database has no other skills named acp-dev-patterns.

Database snapshot: 13.11.2026 · package version 6718d633cc46 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 90acp-conformance
    Validate an ACP implementation against the protocol specification — schema validation, flow testing, error handling, idempotency, security checks, and production readiness. Use when preparing for launch or certifying compliance.
  • 100a2a-dev-patterns
    Apply A2A cross-cutting development patterns — orchestration topologies, idempotency, observability, agent registries, versioning, and production deployment. Use when architecting multi-agent systems or solving cross-cutting concerns.
  • 100arc42-chapter-08-cross-cutting-concepts
    Best practices for arc42 Chapter 8 "Cross-cutting Concepts". Use when documenting cross-cutting architecture concepts, identifying reusable patterns, describing domain models, security concepts, error handling strategies, or explaining HOW the architecture works across multiple…
  • 100acpremote
    Use for `acpremote` tasks: exposing ACP agents or stdio ACP commands over WebSocket, mirroring remote ACP endpoints locally, host ownership semantics, metadata/auth routes, and remote transport examples.
  • 100acp-service
    使用 @1agents/acp-service 管理 ACP 会话与 DSH 插件,通过 A2A 调用固定角色、派发临时任务、查询父子任务和执行轮次、记录业务验收及处理通知,并回投 Codex/DSH 原会话。也用于项目/角色候选探查、目标登记、网络技能缓存和更新接口接入;不用于无关的系统巡检或模型配置。
  • 100reset-cursor-acp
    Reset a stuck Cursor ACP thread in your chat app and reload its configuration. Use only when the user explicitly invokes /reset-cursor-acp.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.