오류

Management API, Content Delivery API, Customer API는 모두 동일한 형식으로 오류를 반환합니다. 각 코드는 모든 API에서 항상 동일한 HTTP 상태 코드와 매핑되므로, 하나의 오류 핸들러로 모든 API를 처리할 수 있습니다.

{
  "error": {
    "code": "SLUG_TAKEN",
    "message": "Another post already uses this slug.",
    "details": { "slug": "how-we-feed-our-starter" }
  }
}

성공적인 응답에는 error가 포함되지 않으며, API가 성공 여부를 ok 플래그로 감싸지도 않습니다.

코드별 HTTP 상태

모든 코드는 하나의 상태와 매핑됩니다. 나중에 추가되는 코드도 동일한 규칙을 따르므로, 아직 확인하지 못한 코드라도 상태를 기준으로 처리할 수 있습니다.

API 레퍼런스의 각 작업에는 반환 가능한 코드와 해당 작업에서의 의미가 나열되어 있습니다. OpenAPI 문서에도 x-kanorio-errors로 동일한 목록이 포함되어 있습니다.

유효성 검사 오류

VALIDATION은 details.issues 내의 모든 실패한 필드를 나열합니다. path는 점(dot)을 사용하여 중첩 구조를 나타냅니다.

{
  "error": {
    "code": "VALIDATION",
    "message": "Input does not match the capability schema.",
    "details": {
      "issues": [
        { "path": "title", "message": "Required", "code": "invalid_type" }
      ]
    }
  }
}

Content Delivery API에서 폼 제출 시 유효하지 않은 답변이 있을 경우 동일한 방식으로 보고되며, path에는 질문 ID가 사용됩니다.

재시도(Retry)

• 429, 502, 503 오류는 백오프(backoff)를 사용하여 재시도하십시오. 응답에 Retry-After 헤더나 details.retryAfter가 포함된 경우, 해당 시간(초)만큼 대기하십시오.
• 다른 4xx 응답은 수정 없이 재시도하지 마십시오. 먼저 요청을 수정해야 합니다.
• 쓰기 작업 중 409 CONFLICT가 발생하면, 읽기 작업 이후 누군가 리소스를 변경했음을 의미합니다. 리소스를 다시 읽고 병합한 다음, 새로운 타임스탬프로 쓰기 요청을 보내십시오.
• 생성 요청은 멱등성 키를 사용하여 안전하게 재시도할 수 있도록 하십시오.

권한 오류

403 응답의 details에는 무엇이 부족한지 설명되어 있습니다. 예를 들어 토큰에 부족한 requiredScope나, 서비스 계정이 계정 수준의 작업을 호출했을 때의 reason: "principal_not_allowed" 등이 포함됩니다. 재시도하는 대신 사용자에게 무엇을 수정해야 하는지 안내하십시오.

요청 ID(Request IDs)

Content Delivery API와 Customer API 응답에는 X-Request-Id 헤더가 포함됩니다. 특정 요청에 대해 지원팀에 문의할 때 이 ID를 함께 제공하십시오.

오류 코드

아래 표는 OpenAPI 문서에서 생성된, 각 API가 현재 반환할 수 있는 모든 코드 목록입니다.

Management API codes

Content Delivery API codes

Customer API codes