Mã lỗi

Hình dạng body lỗi v1 có thể trả về, và bảng tra mã issue → HTTP status cho nhóm auth/registry/signing dùng chung (V1_ISSUE_STATUS).

Hình dạng body lỗi

V1Error

Body lỗi dùng chung cho mọi lỗi auth/registry/signing/origin/pool (SHIELD_KEY_*, SCOPE_DENIED, ORIGIN_NOT_ALLOWED, POOL_MISMATCH, SHIELD_REGISTRY_*, PAYMENT_ENV_MISMATCH, CAPTURED_PROOF_UNAVAILABLE). message/docs LUÔN có mặt. Khác với LegacyControllerError dưới đây — hình dạng lỗi theo từng endpoint của PayPal/Stripe — không bao giờ mang message/docs.

trường	kiểu		mô tả
`error`	boolean	bắt buộc
`data`	object	bắt buộc	`issue` string bắt buộc Mọi mã issue một response v1 có thể mang. Nhóm đầu tiên (SHIELD_KEY_, SCOPE_DENIED, ORIGIN_NOT_ALLOWED, POOL_MISMATCH, SHIELD_REGISTRY_, SHIELD_ENV_MISCONFIGURED, PAYMENT_ENV_MISMATCH, SIGNING_UNAVAILABLE, LEGACY_API_DISABLED, CAPTURED_PROOF_UNAVAILABLE) là bảng auth/registry/signing v1 dùng chung (bảng V1_ISSUE_STATUS dùng chung — được contract-test khớp 1:1). Các mã còn lại là các issue validate/business theo từng endpoint do các controller PayPal/Stripe bên dưới trả về (cùng mã mà API legacy trả về cho cùng endpoint). NGOẠI LỆ: `STRIPE_ERROR` được liệt kê ở đây như giá trị fallback literal, nhưng response 500 của Stripe create-intent/complete KHÔNG đóng với enum này — xem `StripeErrorPassthrough`, nơi ghi lại `issue` là `error.code` mở của chính Stripe. `message` string bắt buộc `docs` string bắt buộc

LegacyControllerError

Body lỗi theo từng endpoint của PayPal/Stripe — CÙNG hình dạng mà API cũ (không-v1) luôn trả về cho các route này. Chỉ issue được đảm bảo; message/docs KHÔNG BAO GIỜ có mặt (khác với V1Error). Một vài response không mang data nào cả — xem mô tả riêng của từng response để biết body chính xác.

trường	kiểu		mô tả
`error`	boolean	bắt buộc
`data`	object	bắt buộc	`issue` string bắt buộc Mọi mã issue một response v1 có thể mang. Nhóm đầu tiên (SHIELD_KEY_, SCOPE_DENIED, ORIGIN_NOT_ALLOWED, POOL_MISMATCH, SHIELD_REGISTRY_, SHIELD_ENV_MISCONFIGURED, PAYMENT_ENV_MISMATCH, SIGNING_UNAVAILABLE, LEGACY_API_DISABLED, CAPTURED_PROOF_UNAVAILABLE) là bảng auth/registry/signing v1 dùng chung (bảng V1_ISSUE_STATUS dùng chung — được contract-test khớp 1:1). Các mã còn lại là các issue validate/business theo từng endpoint do các controller PayPal/Stripe bên dưới trả về (cùng mã mà API legacy trả về cho cùng endpoint). NGOẠI LỆ: `STRIPE_ERROR` được liệt kê ở đây như giá trị fallback literal, nhưng response 500 của Stripe create-intent/complete KHÔNG đóng với enum này — xem `StripeErrorPassthrough`, nơi ghi lại `issue` là `error.code` mở của chính Stripe. `details` array tùy chọn chi tiết validate theo field tùy chọn (ví dụ INVALID_SHIPPING_ADDRESS) mảng gồm: `status` string tùy chọn echo trạng thái phía nhà cung cấp tùy chọn (ví dụ Stripe PaymentIntent.status khi NOT_SUCCEEDED) `message` string tùy chọn chỉ có mặt khi STRIPE_ERROR (chuyển tiếp error.message của Stripe)

LegacyStringError

Body {error:string} trần không có data nào cả — khác với LegacyGateError (cùng hình dạng) và với V1Error/LegacyControllerError (có mang data). Dùng cho các lỗi cấu hình/nội bộ chung: "Shield misconfigured" (lệch chế độ key pk/sk của Stripe), "Internal server error" (lỗi không xác định), "Shield unavailable" (shield chưa được cấu hình secret trên route PayPal).

trường	kiểu		mô tả
`error`	string	bắt buộc

LegacyGateError

Body trần từ gate phân giải pk của Stripe và gate hostname của PayPal — error ở đây là một STRING, không phải true, và không có data/issue nào cả. Bao gồm Stripe MISSING_PK/UNKNOWN_PK/PK_POOL_MISMATCH và gate unknown-host/no-secret của PayPal; tên issue trong mô tả của từng response chỉ mang tính tài liệu, không bao giờ có mặt trong body thực tế.

trường	kiểu		mô tả
`error`	string	bắt buộc

StripeErrorPassthrough

Body 500 trên /v1/stripe/create-intent và /v1/stripe/complete khi lời gọi API Stripe gốc throw lỗi. issue là MỞ — nó chuyển tiếp nguyên văn error.code của Stripe (ví dụ card_declined, parameter_invalid_integer, amount_too_small) khi Stripe đặt một giá trị, chỉ fallback về chuỗi literal STRIPE_ERROR khi không có. KHÔNG phải thành viên của enum đóng V1Issue — không validate issue dựa trên enum đó cho response này.

trường	kiểu		mô tả
`error`	boolean	bắt buộc
`data`	object	bắt buộc	`issue` string bắt buộc error.code của Stripe, hoặc 'STRIPE_ERROR' khi Stripe không cung cấp `message` string bắt buộc error.message của Stripe, hoặc 'unknown'

Bảng mã issue

issue	HTTP status
`SHIELD_KEY_INVALID`	401
`SHIELD_KEY_ENV_MISMATCH`	401
`SHIELD_KEY_REVOKED`	401
`SHIELD_KEY_EXPIRED`	401
`SCOPE_DENIED`	403
`ORIGIN_NOT_ALLOWED`	403
`POOL_MISMATCH`	403
`SHIELD_REGISTRY_UNAVAILABLE`	503
`SHIELD_REGISTRY_STALE`	503
`SHIELD_ENV_MISCONFIGURED`	503
`PAYMENT_ENV_MISMATCH`	503
`SIGNING_UNAVAILABLE`	503
`LEGACY_API_DISABLED`	410
`CAPTURED_PROOF_UNAVAILABLE`	502

STRIPE_ERROR và các issue theo endpoint khác (validate/business) không nằm trong bảng dùng-chung trên — xem mô tả response của từng endpoint trên trang tag tương ứng.