API 오류 형식과 오류 코드

API의 모든 오류 응답은 같은 형식입니다. 코드에서는 message의 텍스트가 아니라 error 필드의 오류 코드를 기준으로 처리하세요. 코드는 변하지 않지만, 텍스트는 바뀔 수 있고 계정 언어로 번역됩니다.

#오류 응답의 구조

{
  "error": "validation_failed",
  "message": "Some of the information provided is invalid. Please check and try again.",
  "details": [
    { "field": "title", "reason": "minLength", "message": "…" }
  ],
  "request_id": "6b1f0c2e-…"
}

error

기계가 읽을 수 있는 코드입니다. 예: not_found. 대부분의 오류에서는 X-Error-Code 헤더에도 들어 있지만, 본문의 필드를 기준으로 하세요.

message

계정 언어로 된 사람이 읽을 수 있는 설명입니다. API 키에서는 워크스페이스 소유자의 언어, 연결된 앱에서는 연결한 사람의 언어입니다. 토큰 검사의 401처럼 유효한 토큰이 없으면 언어는 Accept-Language를 따르고, 그것도 없으면 영어입니다. Content-Language 헤더가 언어를 알려 줍니다.

details

더 알려 줄 내용이 있을 때만 있습니다. 입력값 검증의 422에서는 문제마다 field, reason, message가 있는 목록이고, 비즈니스 로직의 422와 그 밖의 모든 오류에서는 reason, retry_after_sec, issues 목록 같은 내용이 있는 객체입니다. 크기를 넘으면 field, reason, limit이 들어 있고, 413 request_too_large에서는 max_bytes와 max_kb가 들어 있습니다. 따라서 details가 목록인지 확인하세요.

request_id

요청의 ID입니다. X-Request-Id 헤더에도 있습니다. 지원팀에 문의할 때 함께 알려 주세요.

예외: 429 rate_limited 응답에는 details 대신 retry_after_sec 필드가 있으며, 429와 403 insufficient_scope에서는 본문에 request_id가 없습니다. 토큰 검사의 401과 스키마 검사의 422에는 X-Error-Code 헤더가 없으며, 스키마 검사에서는 최상위 message만 번역되고 details 안의 텍스트는 영어로 남습니다. X-Request-Id 헤더는 항상 설정됩니다.

#가장 중요한 코드

#입력 오류 읽기

422 validation_failed에서는 details에 모든 문제가 따로 나열됩니다. field는 필드의 경로(중첩된 객체는 슬래시로 구분. 예: theme_config/button_style)이고, reason은 어긴 규칙(required, minLength, maxLength, enum, additionalProperties 등)입니다. additionalProperties에서는 message가 어떤 필드를 모르는지 알려 줍니다. 필드 이름의 오타인 경우가 많습니다.

#코드에서 권장하는 처리

• 400, 413, 422: 다시 시도하지 말고 요청을 고치기
• 401 invalid_token: 새 토큰을 한 번 받고 다시 시도
• 403: 다시 시도하지 말고 스코프, 플랜, 누가 이 작업을 할 수 있는지 확인
• 404: ID 확인. 삭제한 뒤라면 정상
• 409: 상태를 다시 불러오고 작업이 아직 필요한지 판단
• 429: Retry-After만큼 기다린 뒤 다시 시도(요청 한도 참고)
• 500과 503: 간격을 늘려 가며 몇 번 다시 시도