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 kèm mã trạng thái HTTP phù hợp.

Định dạng lỗi

Mọi lỗi đều có 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	Thiếu hoặc sai tham số, đạt giới hạn gói hoặc hạn mức, tính năng yêu cầu gói cao hơn, hoặc không được ủy quyền — mọi lỗi xác thực dữ liệu đều trả về 400
402	Payment Required	Dành riêng cho trường hợp hết tín dụng. API badges hiện không trừ tín dụng, nên trên thực tế mã này không bao giờ được trả về
404	Not Found	Tài nguyên được yêu cầu không tồn tại
500	Internal Server Error	Đã xảy ra lỗi không mong muốn trên máy chủ

Không có 403 hay 429: lỗi ủy quyền trả về 400 ("not authorized") và không có giới hạn tốc độ ở tầng ứng dụng.

Các lỗi thường gặp và cách khắc phục

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

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

Cách khắc phục: Hãy đưa đầy đủ các tham số bắt buộc vào nội dung yêu cầu. Xem tài liệu của endpoint để biết danh sách đầy đủ.

Email không hợp lệ

{ "error": "invalid email" }

Cách khắc phục: 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" }

Cách khắc phục: Cung cấp URL đầy đủ, bao gồm giao thức, ví dụ https://example.com.

Tên quá ngắn

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

Cách khắc phục: Hãy dùng tên dài hơn. Tên tổ chức 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ự.

Tổ chức cấp chưa được xác minh

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

Cách khắc phục: Hãy xác minh tổ chức cấp trước. Kiểm tra email của tổ chức cấp để tìm liên kết xác minh, hoặc dùng endpoint Xác minh tổ chức cấp.

Đạt hạn mức chứng chỉ (400)

{ "error": "Your Free plan reached its credential limit (1200/1200) — your allowance renews on your plan anniversary, or upgrade to Starter" }

Cách khắc phục: Bạn đã dùng hết toàn bộ quỹ chứng chỉ hằng năm (Free: 1.200/năm, Starter: 12.000/năm, Pro: 120.000/năm). Quỹ này được đặt lại vào ngày kỷ niệm đăng ký tài khoản của bạn — không phải theo mốc tháng dương lịch. Hãy nâng cấp gói để có hạn mức cao hơn. Xem Gói & Thanh toán.

Đạt giới hạn gói (400)

{ "error": "Your Free plan reached its issuer limit (2/2) — delete an issuer or upgrade to Starter" }

Giới hạn huy hiệu có cùng dạng:

{ "error": "badge limit reached (5/5 on the starter plan) — delete a badge or upgrade your plan" }

Cách khắc phục: Bạn đã chạm mức tối đa của gói về số tổ chức cấp hoặc huy hiệu. Hãy xóa tài nguyên không dùng hoặc nâng cấp gói.

Tài nguyên còn phụ thuộc (400)

{ "error": "issuer has 3 badge(s) linked — delete the badges first" }

Cách khắc phục: Hãy xóa tất cả huy hiệu liên kết với tổ chức cấp trước khi xóa tổ chức cấp đó. Tương tự, hãy xóa tất cả chứng chỉ thuộc một huy hiệu trước khi xóa huy hiệu.

Không được ủy quyền (400)

{ "error": "not authorized" }

Lỗi ủy quyền là lỗi xác thực dữ liệu, nên trả về 400 (không phải 401 hay 403).

Cách khắc phục: Bạn chỉ có thể sửa đổi các tài nguyên do bạn sở hữu. Hãy đảm bảo bạn đang dùng đúng khóa API.

HTML trong văn bản chia sẻ

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

Cách khắc phục: Văn bản chia sẻ phải là văn bản thuần. Hãy xóa mọi thẻ HTML khỏi tham số text.