에러 처리

SocFlow API 사용 중 오류가 발생할 수 있습니다. 이 가이드에서는 다양한 에러 타입과 상태 코드, 그리고 문제 해결 방법에 대해 알아봅니다.

API 응답의 상태 코드와 에러 메시지를 통해 무엇이 잘못되었는지 파악하고 디버깅할 수 있습니다. 모든 에러 응답은 표준화된 형식을 따르므로 일관되게 처리할 수 있습니다.

대부분의 에러는 잘못된 요청 형식이나 누락된 필드로 인해 발생합니다. 에러 메시지를 주의 깊게 읽고 요청 데이터를 확인하세요.

에러 응답 구조

SocFlow API의 모든 에러 응답은 동일한 JSON 구조를 따릅니다.

에러 응답에는 항상 success: false와 errors 배열이 포함됩니다. errors 배열에는 하나 이상의 에러 객체가 포함되며, 각 객체는 에러 코드와 메시지를 담고 있습니다.

응답 필드

Name
success
Type
boolean
Description
항상 false를 반환합니다.
Name
errors
Type
array
Description
발생한 에러들의 배열입니다.
Name
errors[].code
Type
string
Description
에러를 식별하는 고유 코드입니다.
Name
errors[].message
Type
string
Description
에러에 대한 사용자 친화적인 설명입니다.
Name
errors[].field
Type
string
Description
(선택) 에러가 발생한 필드명입니다.

에러 응답 예시

{
  "success": false,
  "errors": [
    {
      "code": "4001",
      "message": "Required field 'caption' is missing",
      "field": "caption"
    }
  ]
}

HTTP 상태 코드

API 요청의 성공 여부는 HTTP 상태 코드로 확인할 수 있습니다.

Name
200 OK
Description
요청이 성공적으로 처리되었습니다.
Name
201 Created
Description
리소스가 성공적으로 생성되었습니다.
Name
400 Bad Request
Description
클라이언트 요청에 오류가 있습니다. 요청 데이터를 확인하세요.
Name
401 Unauthorized
Description
인증이 필요합니다. API 키를 확인하세요.
Name
403 Forbidden
Description
해당 리소스에 접근할 권한이 없습니다.
Name
404 Not Found
Description
요청한 리소스를 찾을 수 없습니다.
Name
409 Conflict
Description
리소스 충돌이 발생했습니다. (예: 중복된 데이터)
Name
429 Too Many Requests
Description
Rate Limit을 초과했습니다. 요청 속도를 줄이세요.
Name
500 Internal Server Error
Description
서버 내부 오류가 발생했습니다. 지원팀에 문의하세요.

에러 코드 분류

SocFlow API는 에러의 원인에 따라 코드를 분류합니다.

4000번대: 검증 에러

클라이언트 요청의 유효성 검증 실패 시 반환됩니다.

Name
4000
Description
일반 검증 에러 - Zod 스키마 검증 실패
Name
4001
Description
필수 필드 누락 - 필수 필드가 요청에 포함되지 않음
Name
4002
Description
타입 불일치 - 필드 타입이 스키마와 일치하지 않음
Name
4003
Description
형식 오류 - 데이터 형식이 올바르지 않음 (예: datetime)

검증 에러 예시

{
  "success": false,
  "errors": [
    {
      "code": "4001",
      "message": "Required field 'media_url' is missing",
      "field": "media_url"
    }
  ]
}

5000번대: 데이터베이스 에러

데이터베이스 작업 중 발생하는 에러입니다.

Name
5001
Description
데이터베이스 연결 오류 - DB 연결 실패
Name
5002
Description
쿼리 실행 오류 - SQL 쿼리 실행 실패
Name
5003
Description
데이터 무결성 오류 - 제약 조건 위반 (예: 중복 키)

데이터베이스 에러 예시

{
  "success": false,
  "errors": [
    {
      "code": "5003",
      "message": "Duplicate key violation: resource already exists"
    }
  ]
}

7000번대: 서버 내부 에러

예기치 않은 서버 오류입니다.

Name
7000
Description
내부 서버 오류 - 예기치 않은 서버 에러가 발생했습니다. 이 에러가 지속되면 고객 지원팀에 문의하세요.

서버 에러 예시

{
  "success": false,
  "errors": [
    {
      "code": "7000",
      "message": "Internal Server Error"
    }
  ]
}

8000번대: 비즈니스 로직 에러

애플리케이션 비즈니스 로직에서 발생하는 에러입니다.

Name
8001
Description
리소스 중복 - 이미 존재하는 리소스를 생성하려고 시도
Name
8002
Description
리소스 없음 - 존재하지 않는 리소스에 접근
Name
8003
Description
권한 부족 - 해당 작업을 수행할 권한이 없음

비즈니스 에러 예시

{
  "success": false,
  "errors": [
    {
      "code": "8002",
      "message": "Social account not found",
      "field": "account_id"
    }
  ]
}

에러 처리 권장사항

1. 에러 코드로 분기 처리

async function createPost(data) {
  try {
    const response = await fetch('https://api.socflow.app/api/v1/posts', {
      method: 'POST',
      headers: {
        'X-Secret-Token': process.env.SOCFLOW_API_KEY,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify(data)
    });

    const result = await response.json();

    if (!result.success) {
      const error = result.errors[0];
      
      switch (error.code) {
        case '4001':
          console.error('필수 필드 누락:', error.field);
          break;
        case '8001':
          console.error('리소스 중복:', error.message);
          break;
        case '8002':
          console.error('리소스 없음:', error.message);
          break;
        default:
          console.error('에러 발생:', error.message);
      }
      
      throw new Error(error.message);
    }

    return result.data;
  } catch (error) {
    console.error('API 호출 실패:', error);
    throw error;
  }
}

2. 재시도 로직 구현

일시적인 오류(5xx, 429)의 경우 재시도를 권장합니다.

async function apiCallWithRetry(url, options, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      const response = await fetch(url, options);
      const result = await response.json();
      
      if (result.success) {
        return result;
      }
      
      // 재시도 가능한 에러인지 확인
      if (response.status >= 500 || response.status === 429) {
        const delay = Math.pow(2, i) * 1000; // Exponential backoff
        await new Promise(resolve => setTimeout(resolve, delay));
        continue;
      }
      
      // 재시도 불가능한 에러는 바로 throw
      throw new Error(result.errors[0].message);
    } catch (error) {
      if (i === maxRetries - 1) throw error;
    }
  }
}

에러가 지속되거나 해결 방법을 찾을 수 없는 경우 고객 지원으로 문의하세요.