dev/atlas
한국어
/> API design

API Error Envelope

API 오류 응답 형식

A consistent code, message, and details shape simplifies client handling across failures.

···
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)
···

Schema Validation스키마 검증

Validate input types, required fields, and ranges against a schema at the API boundary.

···

API ContractAPI 계약

Paths, requests, responses, and failures form a shared promise between client and server.

···

GraphQL QueryGraphQL 질의

Clients select the fields they need, and responses follow that selection.

···

GraphQL N+1 ProblemGraphQL N+1 문제

Resolving a related field separately for every row multiplies database calls.

An error envelope gives clients stable places to find a code and details across failure types. The HTTP status gives the broad class; a body code distinguishes an actionable condition in the product. Validation failures can put field causes in details.

The demo maps validation, authorization, and server failures into one shape. Do not expose stacks or secrets in public messages, and document the meaning of stable codes.

When to use

Use it when frontends and SDKs need shared error handling across endpoints.

Open as page ↗