Response 규격화에 대한 의견

[GentleDot]

PaymentError

package com.inner.circle.core.payment.claims.dto

data class PaymentError(
    val code: String,
    val message: String
)

PaymentResponse

package com.inner.circle.core.payment.claims.dto

data class PaymentResponse<T> private constructor(
    val success: Boolean,
    val data: T?,
    val error: PaymentError?
) {
    companion object {
        fun <T> ok(data: T): PaymentResponse<T> =
            PaymentResponse(success = true, data = data, error = null)

        fun fail(error: PaymentError): PaymentResponse<Nothing> =
            PaymentResponse(success = false, data = null, error = error)
    }
}

ExceptionHandler 구성 예

package com.inner.circle.api.payment.claims.exception

import com.inner.circle.core.payment.claims.dto.PaymentError
import com.inner.circle.core.payment.claims.dto.PaymentResponse
import org.springframework.http.HttpStatus
import org.springframework.http.ResponseEntity
import org.springframework.web.bind.annotation.ExceptionHandler
import org.springframework.web.bind.annotation.RestControllerAdvice

@RestControllerAdvice
class GlobalExceptionHandler {
    @ExceptionHandler(Exception::class)
    fun handleException(ex: Exception): ResponseEntity<PaymentResponse<Nothing>> {
        val status = HttpStatus.INTERNAL_SERVER_ERROR
        val errorResponse =
            PaymentResponse.fail(
                PaymentError(status.toString(), "Unexpected error occurred.")
            )
        return ResponseEntity(errorResponse, status)
    }

    @ExceptionHandler(IllegalArgumentException::class)
    fun handleIllegalArgumentException(
        ex: IllegalArgumentException
    ): ResponseEntity<PaymentResponse<Nothing>> {
        val status = HttpStatus.BAD_REQUEST
        val errorResponse =
            PaymentResponse.fail(
                PaymentError(status.toString(), "Invalid request")
            )
        return ResponseEntity(errorResponse, status)
    }
}

---

{
"success": "boolean",
"data": {
reponseData: T
},
"error": "string"
}

형식으로 응답을 내려줄 수 있도록 구상한 내용입니다.

응답 예시

• 성공 시

{
"success": true,
"data": {
"orderId": "a1b2c3d4-e5f6-7g8h-9i0j-k1l2m3n4o5p6",
"registeredAt": "2025-10-05T14:48:00",
"message": "Payment request sent to PG server."
},
"error": null
} 

• 실패 시

{
"success": false,
"data": null,
"error": {
    code : 403,
    message : forbidden
    }
}

[Raemerrr]

이것도 멘토링 시간에 의견 들어보고, FE분들이 어떤 응답이 편하실지 논의해보면 좋겠네요!

저는 HTTP Status Code에 충분히 담겨있다고 생각해서 아래와 같은 모습을 생각했습니다.

성공 시

HTTP Status Code: 200
{
  "orderId": "a1b2c3d4-e5f6-7g8h-9i0j-k1l2m3n4o5p6",
  "registeredAt": "2025-10-05T14:48:00",
  "message": "Payment request sent to PG server."
}

실패 시

HTTP Status Code: 403
{
  "message": "forbidden"
}

[GentleDot]

좀 더 심플하게 전달하는것도 괜찮을 것 같아요. 😄
client 분들의 response 객체 구성이 용이한 형태로 정해지면 좋습니다.

[H-Genie]

성공시에는 에러 객체가 필요없을것 같고
실패시에는 데이터 객체가 필요없을것 같습니다
그리고 success라는 키를 ok로 바꿔주시면 좋을것 같습니다

• 성공시
  {
  "ok": true,
  "data": {
  "orderId": "a1b2c3d4-e5f6-7g8h-9i0j-k1l2m3n4o5p6",
  "registeredAt": "2025-10-05T14:48:00",
  "message": "Payment request sent to PG server."
  }
  }

• 실패시
  {
  "ok": false,
  "error": {
  code : 403,
  message : forbidden
  }
  }

[youabledev]

제가 클라이언트 쪽 담당했었을 때는 아래와 같은 구조가 작업하기 편했던거 같아요

성공시

"code": "00000",
"msg": "success",
"data": {
    "orderId": "a1b2c3d4-e5f6-7g8h-9i0j-k1l2m3n4o5p6",
    "registeredAt": "2025-10-05T14:48:00",
}

실패시

"code": "10000", // <- 해당 코드로 UI 를 분기 처리 하는데 사용할 수도 있습니다.
"msg": "인증된 사용자가 아닙니다.", // <- 이 메세지를 사용해서 주로 얼럿 창에 보여줬었습니다
"data": null

http status code도 확인하긴 하지만 성공이든 실패든 동일한 형태의 body가 내려오면 작업하기 훨씬 수월했었습니다!
그렇더라도 현재 프론트 작업하시는 분들의 의견을 듣고 정의하는게 가장 좋을 듯 합니다