Giao diện
Mã lỗi
Trang sinh tự động
Nguồn: code/apps/api/supabase/functions/_shared/errors.ts. Không sửa tay.
Client chỉ rẽ nhánh theo extensions.code, không parse message. Đây là toàn bộ danh sách mã; lỗi không mang mã nào trong số này ra khỏi server dưới dạng internal với message cố định — không rò message gốc, SQL, stack hay secret.
Edge Function không phải GraphQL dùng cùng bộ mã trong { error: { code, message, details } }.
extensions.code | HTTP | Message mặc định |
|---|---|---|
unauthorized | 401 | Chưa đăng nhập. |
forbidden | 403 | Không có quyền thực hiện thao tác này. |
not_found | 404 | |
validation_failed | 422 | |
conflict | 409 | |
internal | 500 | |
otp_invalid | 422 | |
too_many_requests | 429 | |
stale_version | 409 | |
policy_undecided | 409 | |
provider_unknown | 502 |
11 mã. Ba mã conflict, stale_version, policy_undecided dùng cùng HTTP 409 nhưng khác nhau về ý nghĩa, nên client phải đọc code chứ không đọc status.
Dùng mã nào khi nào
Phần này mô tả quy ước, nguồn là docs/contracts/api-conventions.md §2:
validation_failedmangdetailstheoflatten()của Zod (formErrors,fieldErrors), cộngreasonvàfieldkhi có.conflictmangdetails.reason, ví dụidempotency_key_reusekhi dùng lạirequestIdvới payload khác.stale_versionmangexpectedVersionvàactualVersion.provider_unknownnghĩa là nhà cung cấp chưa trả lời dứt khoát — client phải hỏi lại trạng thái hoặc thử lại với cùngrequestId, không được coi là thất bại rồi tạo thanh toán mới.