> For the complete documentation index, see [llms.txt](https://docs.loomgate.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.loomgate.io/api-reference/errors.md). # Mã lỗi Định dạng lỗi, HTTP status và danh sách mã lỗi kèm cách xử lý. Mọi lỗi có dạng: ```json { "error": { "type": "invalid_request_error", "code": "refund_exceeds_remaining", "message": "Refund amount exceeds what can still be refunded (fees are not refundable).", "param": "amount" } } ``` * `type`: nhóm lỗi, quyết định HTTP status. * `code`: mã cụ thể, dùng trong code của bạn. * `message`: tiếng Anh, không chứa thông tin nhạy cảm. Đừng so sánh chuỗi này trong code vì nó có thể đổi. * `param`: trường gây lỗi (nếu có), ví dụ `items[0].quantity`. * `decline_code`: chỉ có khi thẻ bị từ chối và biết lý do. ## Nhóm lỗi | `type` | HTTP | Nghĩa | | ----------------------- | ------------- | ----------------------------------------------------- | | `invalid_request_error` | 400, 404, 409 | Request sai, không tìm thấy, hoặc xung đột trạng thái | | `authentication_error` | 401 | Key hoặc client secret sai | | `card_error` | 402 | Thẻ bị từ chối hoặc thanh toán thất bại | | `rate_limit_error` | 429 | Quá giới hạn, xem header `Retry-After` | | `api_error` | 500, 502 | Lỗi phía Loomgate hoặc hệ thống thanh toán | API không dùng 403: tài khoản bị tạm ngưng hay chưa được duyệt trả 400. ## Danh sách mã | `code` | HTTP | Nghĩa | Nên làm | | -------------------------------- | ---- | --------------------------------------------------------------------------- | ------------------------------------------------ | | `validation_error` | 400 | Request sai dạng: thiếu trường, sai kiểu, trường lạ, JSON hỏng | Sửa theo `param` | | `invalid_amount` | 400 | Số tiền không phải số nguyên dương | Sửa request | | `amount_too_small` | 400 | Tổng người mua trả dưới 100, hoặc phí bằng/lớn hơn số tiền khi bạn chịu phí | Tăng số tiền | | `amount_too_large` | 400 | Tổng vượt 99 999 999 | Chia nhỏ thanh toán | | `unsupported_currency` | 400 | Tiền tệ khác `usd`, `eur` | Sửa request | | `invalid_billing_details` | 400 | Thông tin thanh toán của người mua thiếu hoặc sai | Sửa theo `param` | | `invalid_payment_details` | 400 | Mặt hàng, người mua, mã đơn hoặc địa chỉ sai quy tắc | Sửa theo `param` | | `payment_details_missing` | 400 | Xác nhận khi payment còn thiếu người mua, mã đơn hoặc địa chỉ giao hàng | Cập nhật payment rồi xác nhận lại | | `non_physical_goods_not_allowed` | 400 | Tài khoản chưa được bán hàng phi vật lý | Liên hệ Loomgate hoặc đại lý | | `payment_intent_not_pending` | 400 | Payment đã xong/đã hủy, hoặc đã dùng hết số lần thử | Tạo payment mới | | `payment_not_refundable` | 400 | Payment chưa thành công, hoặc hệ thống thanh toán từ chối hoàn | Kiểm tra trạng thái payment | | `refund_exceeds_remaining` | 400 | Vượt `amount_refundable` | Giảm số tiền hoàn | | `merchant_suspended` | 400 | Tài khoản đang bị tạm ngưng | Liên hệ Loomgate | | `merchant_not_approved` | 400 | Tài khoản chưa được duyệt | Chờ duyệt | | `invalid_api_key` | 401 | Thiếu hoặc sai API key | Kiểm tra header `Authorization` | | `api_key_revoked` | 401 | Key đã bị thu hồi | Dùng key mới | | `invalid_client_secret` | 401 | `client_secret` sai | Kiểm tra payment đang dùng | | `payment_method_declined` | 402 | Thẻ bị từ chối | Release, mời người mua dùng thẻ khác | | `payment_failed` | 402 | Thanh toán thất bại (ví dụ 3-D Secure không qua) | Release, mời thử lại | | `not_found` | 404 | Route hoặc đối tượng không tồn tại | Kiểm tra URL | | `payment_intent_not_found` | 404 | Không có payment này trong tài khoản của bạn | Kiểm tra id và key | | `refund_not_found` | 404 | Không có refund này | Kiểm tra id | | `idempotency_key_reused` | 409 | Key đã dùng với body khác hoặc ở route khác | Dùng key mới | | `payment_intent_updated` | 409 | Số tiền đã đổi từ lúc form thẻ tải; chưa trừ tiền | Tải lại form, cho người mua xác nhận lại | | `rate_limited` | 429 | Quá giới hạn request hoặc lần thử | Chờ `Retry-After` giây | | `internal_error` | 500 | Lỗi phía Loomgate | Thử lại sau (dùng `Idempotency-Key`) | | `fee_plan_not_configured` | 500 | Tài khoản chưa có biểu phí | Liên hệ Loomgate | | `provider_error` | 502 | Hệ thống thanh toán không xử lý được | Thử lại sau; với xác nhận, đọc lại payment trước | ## Khi nào thử lại * **429, 500, 502, timeout, lỗi mạng**: thử lại với cùng `Idempotency-Key`. Với route không có idempotency (xác nhận, cập nhật), đọc lại đối tượng trước để biết thao tác đã xảy ra hay chưa. * **400, 401, 404, 409**: thử lại nguyên request sẽ lại lỗi; sửa nguyên nhân trước. * **402**: không thử lại cùng thẻ tự động; release rồi để người mua quyết định. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.loomgate.io/api-reference/errors.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.