> ## Documentation Index
> Fetch the complete documentation index at: https://www.helius.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# 오류 코드 FAQ

> Helius RPC 엔드포인트 사용 시 HTTP 오류 코드를 해결하세요. 일반적인 인증, 속도 제한 및 서버 문제를 식별하고 해결하세요.

<AccordionGroup>
  <Accordion title="왜 401 오류가 발생하나요?">
    ## 의미

    <Warning>**401 Unauthorized** - 요청에 유효한 인증 자격 증명이 부족합니다.</Warning>

    ## 일반적인 원인

    * 잘못되었거나 누락된 API 키
    * API 키가 잘못된 위치에 포함됨
    * 액세스 제어 규칙이 요청을 차단함
    * 만료되었거나 취소된 API 키

    ## 해결 방법

    1. **API 키 형식 확인**

       ```
       https://mainnet.helius-rpc.com/?api-key=YOUR_API_KEY
       ```

    2. **API 키 위치 확인**
       * API 키가 쿼리 매개변수에 있는지 확인
       * 여분의 공백이나 문자가 없는지 확인

    3. **액세스 제어 규칙 검토**
       * [대시보드 설정](https://dashboard.helius.dev/)에서 IP 제한 확인
       * 브라우저 요청을 사용하는 경우 도메인이 허용 목록에 있는지 확인

    <Info>자세한 인증 설정은 [Authentication](/docs/ko/api-reference/authentication) 가이드를 참조하세요.</Info>
  </Accordion>

  <Accordion title="왜 429 오류가 발생하나요?">
    ## 의미

    <Warning>**429 Too Many Requests** - 계획의 속도 제한을 초과했습니다.</Warning>

    ## 일반적인 원인

    * 계획이 허용하는 속도보다 빠르게 요청함
    * 순간적인 제한을 초과하는 트래픽 급증
    * 동일한 API 키를 사용하는 여러 애플리케이션
    * 비효율적인 코드로 인해 중복 요청 발생

    ## 해결 방법

    1. **사용량 모니터링**
       * [대시보드](https://dashboard.helius.dev/usage)에서 `Rate Limited Requests` 그래프 확인
       * 제한에 도달한 엔드포인트 검토

    2. **요청 최적화**
       * 가능한 경우 응답 캐시
       * 여러 작업을 단일 호출로 배치
       * 불필요한 폴링이나 중복 요청 제거

    3. **속도 제한 구현**
       * 애플리케이션에서 요청 사이에 지연 추가
       * 재시도 시 지수 백오프 사용

    4. **업그레이드 고려**
       * 상위 요금제를 위해 [Plans & Rate Limits](/docs/ko/billing/plans) 검토

    <Tip>속도 제한은 매 분마다 재설정되므로 일시적인 제한은 보통 빠르게 해결됩니다.</Tip>
  </Accordion>

  <Accordion title="왜 500 오류가 발생하나요?">
    ## 의미

    <Warning>**500 Internal Server Error** - 요청 처리 중 서버 측 오류가 발생했습니다.</Warning>

    ## 일반적인 원인

    * 잘못된 요청 페이로드
    * 서버의 일시적인 문제
    * 서버 오류를 유발하는 잘못된 매개변수
    * 네트워크 연결 문제

    ## 해결 방법

    1. **요청 검증**
       * JSON 페이로드가 올바르게 형식화되었는지 확인
       * 모든 필수 매개변수가 포함되어 있는지 확인
       * 매개변수 유형이 API 사양과 일치하는지 확인

    2. **서비스 상태 확인**
       * [Helius Status Page](https://helius.statuspage.io/)에서 진행 중인 문제 확인
       * 보고된 정전이나 성능 저하가 있는지 확인

    3. **재시도 로직 구현**
       * 몇 초 동안 기다린 후 재시도
       * 여러 번 시도할 때 지수 백오프 사용

    4. **지원 받기**
       * 오류가 지속되면 요청 세부 사항과 함께 지원에 문의
       * 정확한 요청 페이로드와 타임스탬프 포함

    <Note>서버 오류는 일반적으로 일시적이며 자동으로 해결되는 경우가 많습니다.</Note>
  </Accordion>

  <Accordion title="왜 503 오류가 발생하나요?">
    ## 의미

    <Warning>**503 Service Unavailable** - 서버가 일시적으로 과부하 상태이거나 유지 관리 중입니다.</Warning>

    ## 일반적인 원인

    * 높은 트래픽으로 인해 일시적 과부하 발생
    * 예약된 유지 관리
    * 서버 용량 제한 도달
    * 네트워크 인프라 문제

    ## 해결 방법

    1. **기다리기 및 재시도**
       * 30-60초 기다린 후 다시 시도
       * 이 오류는 일반적으로 로드 밸런싱으로 해결됩니다.

    2. **스마트 재시도 구현**
       * 지수 백오프 사용 (1초부터 시작하여 2초, 4초 등)
       * 최대 재시도 제한 설정 (3-5회 시도)
       * 천둥 소리 효과를 피하기 위해 지터 추가

    3. **유지 관리 확인**
       * 예정된 유지 관리에 대해 [Helius Status Page](https://helius.statuspage.io/) 검토
       * 발표된 유지 관리 창을 고려하여 계획 수립

    4. **로드 분산**
       * 가능한 경우 요청을 시간에 걸쳐 분산
       * 과부하 보호를 트리거할 수 있는 버스트 패턴 피하기

    <Tip>503 오류는 일시적이며 서버 부하가 줄어들면서 서비스가 자동으로 복구됩니다.</Tip>
  </Accordion>

  <Accordion title="왜 504 오류가 발생하나요?">
    ## 의미

    <Warning>**504 Gateway Timeout** - 서버가 제한 시간 내에 업스트림 서비스로부터 응답을 받지 못했습니다.</Warning>

    ## 일반적인 원인

    * 네트워크 연결 문제
    * 복잡한 작업이 제한 시간을 초과
    * 네트워크 혼잡이 심한 경우 느린 블록체인 응답
    * 처리하는 데 너무 오래 걸리는 대량 데이터 요청

    ## 해결 방법

    1. **연결 확인**
       * 인터넷 연결이 안정적인지 확인
       * 간단한 요청으로 로컬 문제를 배제

    2. **대량 요청 최적화**
       * 대량 배치 요청을 작은 청크로 나누기
       * 데이터가 많은 쿼리에 페이지 매김 사용
       * 실시간 데이터에 WebSocket 연결 사용 고려

    3. **제한 시간 구현**
       * 클라이언트 코드에서 적절한 제한 시간 값 설정 (30-60초)
       * 재시도 시 제한 시간 오류를 우아하게 처리

    4. **서비스 상태 모니터링**
       * [Helius Status Page](https://helius.statuspage.io/)에서 네트워크 문제 확인
       * 높은 블록체인 혼잡에 대한 보고 검토

    <Note>게이트웨이 타임아웃은 일반적으로 네트워크 혼잡이나 복잡한 작업을 나타냅니다. 대량 요청을 더 작은 부분으로 나누는 것을 고려하세요.</Note>
  </Accordion>
</AccordionGroup>

## 추가 도움이 필요하신가요?

<CardGroup cols={2}>
  <Card title="지원 문의" icon="headset" href="/docs/ko/support/contact-support">
    Discord, 채팅 또는 이메일 지원을 통해 저희 팀의 도움을 받으세요.
  </Card>

  <Card title="상태 페이지" icon="wave-pulse" href="/docs/ko/support/status-page">
    실시간 서비스 가용성 및 성능 정보를 확인하세요.
  </Card>
</CardGroup>