API 오류 응답 형식

API Error Envelope

여러 오류를 일정한 code·message·details 구조로 돌려줘 클라이언트 처리를 단순하게 합니다.

···
html
<div class="viz"><h3>ERROR ENVELOPE</h3><div class="row"><div class="box" id="input">validation</div><span class="arrow">→</span><div class="box code" id="output">400<br>INVALID_FIELD<br>details.email</div></div><div class="muted">status · code · details</div></div>
css
.viz{width:94%;height:88%;max-width:960px;padding:clamp(10px,2vmin,18px);border:1px solid var(--line);border-radius:14px;background:var(--surface);font:600 clamp(12px,1.35vw,16px)/1.35 var(--font-sans,system-ui,sans-serif);display:flex;flex-direction:column;gap:clamp(7px,1.8vmin,13px);overflow:hidden}.viz h3{margin:0;color:var(--accent);font:700 clamp(12px,1.35vw,16px)/1.2 var(--font-sans,system-ui,sans-serif);letter-spacing:.04em}.viz .row{display:flex;align-items:center;justify-content:center;gap:clamp(5px,1.4vmin,12px);flex:1;min-height:0}.viz .box{padding:clamp(5px,1.5vmin,12px);border:1px solid var(--line);border-radius:9px;background:var(--bg);text-align:center}.viz .muted{color:var(--muted)}.viz .accent{color:var(--accent)}.viz .code{font-family:ui-monospace,monospace}.viz .pill{padding:3px 7px;border:1px solid var(--line);border-radius:99px;white-space:nowrap}.viz .active{border-color:var(--accent);background:color-mix(in srgb,var(--accent) 12%,var(--surface))}.viz .arrow{color:var(--accent);font:700 18px ui-monospace,monospace}#output{min-width:47%;border-color:var(--accent-3)}#input{min-width:28%}
js
const cases=[['validation','400','INVALID_FIELD','details.email'],['permission','403','FORBIDDEN','details.scope'],['server','500','INTERNAL','details.requestId']];let i=0;function draw(){const v=cases[i];document.getElementById('input').textContent=v[0];document.getElementById('output').innerHTML=v.slice(1).join('<br>');i=(i+1)%cases.length}draw();setInterval(draw,1500)

오류 응답 형식은 실패 종류가 달라도 클라이언트가 같은 자리에서 오류 코드와 상세 정보를 찾게 합니다. HTTP 상태 코드는 큰 범주를 알리고, 본문 코드는 제품 안에서 처리할 구체적 조건을 구분합니다. 유효성 오류라면 필드별 원인을 details에 담을 수 있습니다.

데모는 입력 오류·권한 오류·서버 오류가 같은 구조에 담기는 모습을 보여줍니다. 내부 스택이나 민감한 값은 공개 메시지에 넣지 말고, 안정적으로 유지할 코드의 의미를 문서화합니다.

언제 쓰나

여러 엔드포인트의 오류를 프런트엔드와 SDK가 공통 처리해야 할 때 씁니다.

페이지로 열기 ↗