에러 코드

에러 응답은 공통 형태로 와요.
HTTP 상태 코드와 본문의 code 필드를 함께 보고 분기하세요.

응답 형태


{
  "statusCode": 403,
  "code": "FORBIDDEN",
  "message": "필요한 권한이 없습니다: refunds:write"
}

404 NOT_FOUND는 진짜 없는 경우와, 키의 상품 범위 밖이라 안 보이는 경우를 모두 포함해요.
범위 밖 리소스는 존재 자체를 숨기기 위해 404로 응답해요.

요청 본문·쿼리가 형식 검증에 실패하면 code 없이 message 배열로 와요.
어떤 필드가 왜 걸렸는지 항목별로 담겨요.


{
  "statusCode": 400,
  "message": [
    "linkId should not be empty",
    "email must be an email"
  ],
  "error": "Bad Request"
}

선언되지 않은 필드는 에러 없이 조용히 무시돼요.
필드 이름 오타는 검증 에러가 아니라 “값이 반영되지 않는” 형태로 나타나니 주의하세요.

같은 요청을 다시 보낼 가치가 있는지는 상태 코드로 판단하세요.

상태	재시도
`429` · `5xx`	잠시 기다렸다가(백오프) 재시도할 가치가 있어요
`400` · `401` · `403` · `404` · `409`	요청·키·상태를 고치기 전엔 재시도해도 결과가 같아요

단, REFUND_IN_PROGRESS처럼 “처리 중” 성격의 409는 예외예요.
잠시 뒤 리소스를 다시 조회해 반영 여부를 확인하고 재시도하세요.

기본 한도는 60초당 120요청이고, 요청 IP 기준으로 계산돼요.
초과하면 아래처럼 응답해요.


{
  "statusCode": 429,
  "code": "RATE_LIMITED",
  "message": "요청이 너무 많습니다. 잠시 후 다시 시도해주세요."
}

리소스마다 추가 코드가 있어요.
자세한 목록은 각 리소스 페이지에서 다뤄요.