응답 & 에러 코드
응답 봉투
발신·설정·조회 API는 공통 봉투로 응답합니다.
{ "ok": true, "code": "0", "message": null }
| 필드 | 설명 |
|---|---|
ok | 처리 성공 여부(boolean) |
code | 결과 코드 문자열. 성공은 "0", 실패는 아래 표 |
message | 사람이 읽는 설명(성공 시 null일 수 있음) |
data | (설정·조회) 카카오 원본 데이터 |
url / name / size | (업로드) 업로드 결과 |
HTTP 상태 & 코드
| HTTP | code | 의미 | 대응 |
|---|---|---|---|
| 401 | — | 토큰 없음/무효 | API Key 확인 |
| 403 | FORBIDDEN | 권한 부족(BrandWrite 필요) | 스코프 상향 |
| 403 | NO_BRAND_SCOPE | 이 브랜드에 인가되지 않은 키 | brandKey 확인 |
| 404 | NO_BRAND | 존재하지 않는 브랜드 | brandKey 확인 |
| 400 | EMPTY | 필수 필드 누락 | 요청 바디 확인 |
| 400 | BAD_RICH | 리치 JSON 파싱 실패 | rich 문자열 검증 |
| 400 | NOT_MULTIPART | 업로드가 multipart 아님 | Content-Type 확인 |
| 400 | NO_FILE | 업로드 파일 없음 | file 파트 확인 |
| 503 | NO_PERSISTENCE | 수신 영속 비활성(조회 폴백) | 잠시 후 재시도 |
카카오 결과 코드
발신이 카카오까지 갔다가 실패하면 code에 카카오/브릿지 정규화 코드가 담깁니다(예: 세션 만료, 중복 등). ok: false면 항상 message를 함께 확인하세요.
처리 원칙
ok: true가 아니면 재시도 전에code를 분기하세요.NO_BRAND_SCOPE·FORBIDDEN같은 인증 오류는 재시도해도 동일하게 실패합니다.- 세션 관련 실패(만료 등)는 새 수신 이벤트로 세션이 재개된 뒤 다시 시도합니다.