오류 응답 형식

Blue의 GraphQL API는 GraphQL 사양에 따라 표준화된 형식으로 오류를 반환합니다. 오류가 발생하면 응답에는 무엇이 잘못되었는지에 대한 자세한 정보가 포함된 errors 배열이 포함됩니다.

예시 오류 응답

{
  "errors": [
    {
      "message": "Todo was not found.",
      "extensions": {
        "code": "TODO_NOT_FOUND"
      }
    }
  ]
}

오류 구조

각 오류 객체는 다음을 포함합니다:

• message: 오류에 대한 사람이 읽을 수 있는 설명
• extensions.code: 프로그래밍적 처리를 위한 기계 가독성 오류 코드

프로덕션 오류 안전성

Blue는 오류 노출에 대한 안전 시스템을 구현합니다:

• 안전한 오류: 클라이언트에게 실제 오류 코드와 메시지를 표시
• 비안전 오류: 민감한 세부정보를 숨기기 위해 일반 INTERNAL_SERVER_ERROR 반환
• 리소스 없음: 모든 *_NOT_FOUND 오류는 안전하다고 간주되며 항상 노출됨

오류 카테고리

Blue는 다음 카테고리로 구성된 108개의 사용자 정의 오류 코드를 정의합니다:

인증 및 권한 오류

리소스 없음 오류 (총 52개)

핵심 리소스

사용자 정의 필드 및 양식

프로젝트 구성 요소

댓글 및 활동

기타 리소스

검증 오류

비즈니스 로직 오류

한계 및 쿼터

리소스 충돌

권한 및 접근 오류

데이터 무결성 오류

Stripe/결제 오류

인증 및 세션 오류

속도 제한

속도 제한은 graphql-rate-limit 패키지에 의해 다양한 구성으로 처리됩니다:

속도 제한에 걸리면, 한도를 초과했다는 메시지가 포함된 표준 GraphQL 오류를 받게 됩니다.

시스템 및 내부 오류

오류 처리 모범 사례

클라이언트 측 처리

try {
  const result = await client.mutate({
    mutation: CREATE_TODO,
    variables: { input }
  });
} catch (error) {
  if (error.graphQLErrors?.length > 0) {
    const errorCode = error.graphQLErrors[0].extensions?.code;
    
    switch (errorCode) {
      case 'UNAUTHENTICATED':
        // Redirect to login
        break;
      case 'TODO_NOT_FOUND':
        // Show "Record not found" message
        break;
      case 'VALIDATION_ERROR':
        // Display validation errors
        break;
      default:
        // Show generic error message
    }
  }
}

일반 오류 시나리오

1. 인증 필요: UNAUTHENTICATED - 사용자가 로그인해야 함
2. 권한 거부: FORBIDDEN - 사용자가 필요한 역할/권한이 없음
3. 리소스 없음: *_NOT_FOUND - 리소스가 존재하지 않거나 사용자가 접근할 수 없음
4. 검증 실패: VALIDATION_ERROR, BAD_USER_INPUT - 입력 매개변수 확인
5. 속도 제한: 속도 제한 헤더를 확인하고 백오프 구현
6. 결제가 필요함: PAYMENT_REQUIRED - 기능에 구독이 필요함

관련 문서

• 인증 - API 요청 인증 방법
• 요청하기 - 요청 형식 및 헤더
• 속도 제한 - 자세한 속도 제한 정보