오류

API 요청이 실패하면 badges.ninja는 적절한 HTTP 상태 코드와 함께 JSON 오류 응답을 반환해요.

오류 형식

모든 오류는 다음 구조를 따라요.

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

상태 코드

코드	의미	발생 시점
400	Bad Request	파라미터가 누락되었거나 유효하지 않음, 플랜 한도 또는 할당량 도달, 더 높은 플랜이 필요한 기능, 또는 권한 없음 — 모든 검증 실패는 400을 반환해요
402	Payment Required	크레딧 소진을 위해 예약된 코드예요. badges API는 현재 크레딧을 차감하지 않으므로 실제로는 이 코드가 반환되지 않아요
404	Not Found	요청한 리소스가 존재하지 않음
500	Internal Server Error	서버에서 예기치 않은 오류가 발생함

403과 429는 없어요. 권한 실패는 400("not authorized")을 반환하며, 애플리케이션 계층의 요청 속도 제한은 없어요.

일반적인 오류와 해결 방법

필수 파라미터 누락

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

해결 방법: 요청 본문에 필수 파라미터를 모두 포함하세요. 전체 목록은 해당 엔드포인트 문서를 확인하세요.

잘못된 이메일

{ "error": "invalid email" }

해결 방법: user@domain.com 형식의 올바른 이메일 주소를 입력하세요.

잘못된 URL

{ "error": "invalid URL" }

해결 방법: 프로토콜을 포함한 전체 URL을 입력하세요. 예: https://example.com.

이름이 너무 짧음

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

해결 방법: 더 긴 이름을 사용하세요. 발급자 이름은 최소 3자, 수령자 이름은 최소 5자가 필요해요.

발급자가 검증되지 않음

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

해결 방법: 먼저 발급자를 검증하세요. 발급자 이메일에서 검증 링크를 확인하거나 발급자 검증 엔드포인트를 사용하세요.

자격 증명 할당량 도달 (400)

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

해결 방법: 연간 자격 증명 풀을 모두 사용했어요(Free: 연 1,200개, Starter: 연 12,000개, Pro: 연 120,000개). 풀은 달력상의 월 경계가 아니라 계정 등록 기념일에 초기화돼요. 더 많은 할당량이 필요하면 플랜을 업그레이드하세요. 플랜 및 결제를 참조하세요.

플랜 한도 도달 (400)

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

배지 한도도 같은 형태예요.

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

해결 방법: 플랜의 발급자 또는 배지 한도에 도달했어요. 사용하지 않는 리소스를 삭제하거나 플랜을 업그레이드하세요.

리소스에 종속 항목이 있음 (400)

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

해결 방법: 발급자를 삭제하기 전에 해당 발급자에 연결된 모든 배지를 삭제하세요. 마찬가지로 배지를 삭제하기 전에 그 배지의 모든 자격 증명을 삭제하세요.

권한 없음 (400)

{ "error": "not authorized" }

권한 실패는 검증 오류이므로 401이나 403이 아니라 400을 반환해요.

해결 방법: 본인이 소유한 리소스만 수정할 수 있어요. 올바른 API 키를 사용하고 있는지 확인하세요.

공유 텍스트에 HTML 포함

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

해결 방법: 공유 텍스트는 일반 텍스트여야 해요. text 파라미터에서 HTML 태그를 제거하세요.