에러 처리

Open API v2의 에러는 RFC 9457 application/problem+json 형식입니다. 발급 배치의 per-recipient 실패는 예외입니다(항상 200 + BatchResultDto — 개념 참조).

Problem 형태

{
  "type": "https://api.kolleges.net/probs/token-scope-insufficient",
  "title": "Token scope insufficient",
  "status": 403,
  "detail": "토큰에 kolleges:openapi:issuance:write scope가 없습니다.",
  "instance": "/v2/clubs/acme/issuances"
}

type은 에러 코드 식별자입니다(가져오는 URL이 아님). 대표 코드: token-scope-insufficient(토큰 scope 부족)와 link-scope-insufficient(해당 클럽에 대한 권한 부족)는 진단을 위해 분리됩니다.

상태 코드

코드	의미	대응
400	요청 형식 오류(스키마 위반)	body/쿼리 수정
401	토큰 없음·만료·변조·타-audience	토큰 재발급
403	scope 부족 · 클럽 권한 없음	필요한 scope로 토큰 재발급
404	리소스 없음	경로·id 확인
409	멱등 충돌 · 상태 충돌	멱등 키·현재 상태 확인
422	도메인 규칙 위반	detail 참조
429	rate limit 초과	백오프 후 재시도
5xx	서버 오류	지수 백오프 재시도

재시도 전략

5xx · 429 · 네트워크 실패 → 지수 백오프로 재시도. 쓰기는 **동일 Idempotency-Key**로 재시도해 중복 발급을 방지하세요.
4xx(429 제외) → 재시도해도 동일 실패입니다. detail을 보고 요청을 고치세요.