응답 봉투와 에러

이 문서에서 가장 먼저 읽어야 할 페이지입니다. 성공이든 실패든 모든 응답이 같은 봉투에 담겨 오는데, 자동 생성된 OpenAPI 문서에는 그 봉투가 그려지지 않습니다. 모르고 짜면 첫 요청부터 값을 찾지 못합니다.

성공 응답

실제로 쓰는 값은 전부 data 안에 있습니다.

{
  "success": true,
  "message": "Request processed successfully",
  "data": {
    "groupId": "grp_01HQZX8N2K4M7P9R3T5V6W8Y0A",
    "status": "QUEUED",
    "sendCount": 1206
  },
  "timestamp": "2026-08-25T14:32:10.482+09:00",
  "method": "POST",
  "path": "/public/v1/messages/alimtalk",
  "correlationId": "c7f1a2b4-9e30-4d15-8a6c-2f0b7d9e1c34"
}

실패 응답

모양이 거의 같지만 두 곳이 다릅니다 — data 가 빠지고 숫자 code 가 붙습니다.

{
  "success": false,
  "message": "유효하지 않은 API 키입니다.",
  "code": 8621,
  "timestamp": "2026-08-25T14:32:10.482+09:00",
  "method": "POST",
  "path": "/public/v1/messages/alimtalk",
  "correlationId": "c7f1a2b4-9e30-4d15-8a6c-2f0b7d9e1c34"
}

• successboolean필수

  실패 응답에서는 항상 `false` 입니다.

  예: false

• messagestring필수

  실패 사유. 그대로 사용자에게 보여 줄 수 있는 한국어 문구입니다.

  예: "유효하지 않은 API 키입니다."

• codenumber선택

  숫자 에러 코드. **항상 오지는 않습니다** — 프레임워크가 먼저 거절한 요청(잘못된 JSON, 없는 경로 등)에는 이 필드가 없습니다. HTTP 상태와 함께 보세요.

  예: 8621

• dataobject선택null 가능

  일부 코드만 싣는 부가 정보 (예: 한도 초과 시 현재값·한도). 없는 경우가 더 많습니다.

• timestampstring필수date-time

  응답을 만든 시각 (KST)

• methodstring필수

  요청 메서드. 요청을 그대로 되비춰 줍니다.

  예: "POST"

• pathstring필수

  요청 경로

  예: "/public/v1/messages/alimtalk"

• correlationIdstring필수

  요청 추적 ID. **문의할 때 이 값을 함께 알려 주세요** — 서버 로그를 이 값으로 찾습니다.

code 를 읽을 때 주의할 것

• 우리가 의도적으로 던진 오류가 아니면 `code` 는 9000 으로 뭉뚱그려집니다. 원인은 `message` 와 `correlationId` 로 구분해 주세요.
• 프레임워크가 먼저 거절한 요청(잘못된 JSON, 너무 큰 본문, 없는 경로 등)에는 `code` 필드가 **아예 없습니다.** `code` 를 필수로 두고 파싱하면 그 경우에 깨집니다 — 항상 HTTP 상태를 함께 보세요.

코드 대역

앞자리로 원인의 갈래를 알 수 있습니다. 정확한 뜻은 각 엔드포인트 페이지의 「에러」 표에 있습니다.

문의할 때

correlationId 를 함께 알려 주세요. 서버 로그를 이 값으로 찾습니다 — 「어제 오후에 실패했어요」보다 훨씬 빠릅니다. 실패 응답을 로그에 남길 때 이 값을 반드시 함께 기록해 두시길 권합니다.