Errors & idempotency

400 means invalid input; 401 means authentication/capability expired or invalid; 403 means scope/access restriction; 404 means record not found or outside your tenant; 409 means stale versions, conflicting idempotency or command state; 429 means rate limiting. A 503 can indicate an unavailable pricing reference or dependency.

Payment, refund and renewal commands use explicit Idempotency-Key headers. Use one cryptographically random key per intended action, persist it on your server and reuse it after a timeout. Changing the body with the same key is a conflict. Do not assume every endpoint accepts or implements idempotency just because a header is sent.

A network timeout is not proof a payment failed. Read the original order before retrying. Never create another payment automatically when the provider may already have accepted the first request. Link generation creates no payment and is safe to repeat.