Lỗi

Khi một yêu cầu API thất bại, badges.ninja trả về phản hồi lỗi JSON với mã trạng thái HTTP phù hợp.

Định dạng lỗi

Mọi lỗi đều theo cấu trúc sau:

{
  "error": "description of what went wrong"
}

Mã trạng thái

Mã	Ý nghĩa	Khi nào xảy ra
400	Bad Request	Tham số bị thiếu hoặc không hợp lệ
402	Payment Required	Đã đạt hạn mức cấp hàng tháng hoặc tính năng cần gói cao hơn
403	Forbidden	Đã đạt giới hạn gói (ví dụ giới hạn đơn vị cấp hoặc huy hiệu)
404	Not Found	Tài nguyên yêu cầu không tồn tại
429	Too Many Requests	Vượt giới hạn tần suất
500	Internal Server Error	Có lỗi không mong đợi xảy ra trên máy chủ

Lỗi thường gặp và cách giải quyết

Thiếu tham số bắt buộc

{ "error": "missing required parameters: name, url, email" }

Giải pháp: Đưa mọi tham số bắt buộc vào thân yêu cầu. Xem tài liệu điểm cuối để có danh sách đầy đủ.

Email không hợp lệ

{ "error": "invalid email" }

Giải pháp: Cung cấp địa chỉ email hợp lệ theo định dạng user@domain.com.

URL không hợp lệ

{ "error": "invalid URL" }

Giải pháp: Cung cấp URL đầy đủ kèm giao thức, ví dụ https://example.com.

Tên quá ngắn

{ "error": "name must be at least 3 characters" }

Giải pháp: Dùng tên dài hơn. Tên đơn vị cấp cần tối thiểu 3 ký tự. Tên người nhận cần tối thiểu 5 ký tự.

Đơn vị cấp chưa xác minh

{ "error": "issuer must be verified before creating badges" }

Giải pháp: Xác minh đơn vị cấp trước. Kiểm tra email đơn vị cấp để có liên kết xác minh, hoặc dùng điểm cuối Xác minh đơn vị cấp.

Đã đạt hạn mức cấp hàng tháng

{ "error": "monthly award quota reached" }

Giải pháp: Bạn đã dùng hết các lần cấp gồm trong gói cho kỳ thanh toán này (Free: 100/mo, Starter: 1,000/mo, Pro: 10,000/mo). Chờ đến lần đặt lại tiếp theo hoặc nâng cấp gói. Xem Gói & Thanh toán.

Đã đạt giới hạn gói

{ "error": "issuer limit reached for your plan" }

Giải pháp: Bạn đã đạt giới hạn gói về đơn vị cấp, huy hiệu hoặc khóa API. Xóa tài nguyên không dùng hoặc nâng cấp gói.

Blockchain cần gói Pro

{ "error": "blockchain verification requires the Pro plan" }

Giải pháp: Tham số blockchain chỉ có trên gói Pro. Nâng cấp để bật xác thực on-chain.

Blockchain không hỗ trợ

{ "error": "unsupported blockchain, only 'matchain' is supported" }

Giải pháp: Hiện chỉ hỗ trợ matchain làm tham số blockchain.

Tài nguyên có phụ thuộc

{ "error": "issuer has badges and cannot be deleted" }

Giải pháp: Xóa mọi huy hiệu dưới đơn vị cấp trước khi xóa đơn vị cấp. Tương tự, xóa mọi lần cấp dưới một huy hiệu trước khi xóa huy hiệu.

Không được phép

{ "error": "not authorized" }

Giải pháp: Bạn chỉ có thể chỉnh sửa các tài nguyên thuộc sở hữu của bạn. Bảo đảm dùng đúng khóa API.

HTML trong văn bản chia sẻ

{ "error": "HTML tags are not allowed" }

Giải pháp: Văn bản chia sẻ phải là văn bản thuần. Loại bỏ mọi thẻ HTML khỏi tham số text.