오류

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

오류 형식

모든 오류는 다음 구조를 따릅니다.

{
  "error": "무엇이 잘못됐는지에 대한 설명"
}

상태 코드

코드	의미	언제 발생
400	Bad Request	파라미터가 누락되었거나 잘못됨
402	Payment Required	월간 수여 할당량 도달 또는 해당 기능이 상위 요금제 필요
403	Forbidden	요금제 한도 도달(예: 발급자 또는 배지 상한)
404	Not Found	요청한 리소스가 없음
429	Too Many Requests	속도 제한 초과
500	Internal Server Error	서버에서 예기치 않은 오류 발생

자주 발생하는 오류와 해결

필수 파라미터 누락

{ "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" }

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

월간 수여 할당량 도달

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

해결: 이 결제 주기 동안 요금제에 포함된 모든 수여를 사용했습니다(Free: 100/월, Starter: 1,000/월, Pro: 10,000/월). 다음 재설정을 기다리거나 요금제를 업그레이드하세요. 요금제와 결제 를 참고하세요.

요금제 한도 도달

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

해결: 요금제의 발급자, 배지, 또는 API 키 상한에 도달했습니다. 사용하지 않는 리소스를 삭제하거나 요금제를 업그레이드하세요.

블록체인은 Pro 필요

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

해결: blockchain 파라미터는 Pro 요금제에서만 사용 가능합니다. 온체인 검증을 활성화하려면 Pro로 업그레이드하세요.

지원하지 않는 블록체인

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

해결: 현재 blockchain 파라미터로는 matchain 만 지원합니다.

의존성이 있는 리소스

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

해결: 발급자를 삭제하기 전에 그 아래의 모든 배지를 삭제하세요. 마찬가지로 배지를 삭제하기 전에 해당 배지의 모든 수여를 먼저 삭제하세요.

권한 없음

{ "error": "not authorized" }

해결: 자신이 소유한 리소스만 수정할 수 있습니다. 올바른 API 키를 사용하는지 확인하세요.

공유 문구에 HTML 포함

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

해결: 공유 문구는 일반 텍스트여야 합니다. 텍스트 파라미터에서 모든 HTML 태그를 제거하세요.