GPT-6 Astra API 오류: 15가지 일반적인 문제와 해결 방법

API 인시던트를 악화시키는 가장 빠른 방법은 모든 오류를 재시도하는 것입니다. 잘못된 스키마는 백오프로 해결되지 않으며, 소진된 크레딧 잔액은 작업자가 열 번 더 시도한다고 해서 회복되지 않습니다. HTTP 상태, SDK 클래스, error.type, 특히 error.code로 오류를 진단하세요.

안전한 오류 처리기

try {
  return await client.responses.create({
    model: "gpt-6-astra",
    입력
  });
} catch (error) {
  if (error instanceof OpenAI.APIConnectionError) {
    // Network, proxy, TLS, DNS or firewall path.
  } else if (error instanceof OpenAI.RateLimitError) {
    // Inspect code and Retry-After before deciding to retry.
  } else if (error instanceof OpenAI.APIError) {
    console.error(error.status, error.message, error.code);
  } else {
    오류를 던지다;
  }
}

요청 ID, 타임스탬프 및 시간대, 모델, 엔드포인트, 상태, 코드, 재시도 횟수, 그리고 정제된 페이로드 특성을 기록하세요. 기본적으로 API 키나 기밀 프롬프트 내용을 절대 기록하지 마세요.

1. 400 잘못된 요청

페이로드가 잘못 구성되었거나 호환되지 않습니다: 잘못된 필드, 누락된 입력, 유효하지 않은 도구 스키마, 지원되지 않는 조합 또는 잘못 인코딩된 콘텐츠입니다. 메시지를 읽고 현재 Responses 참조와 비교한 후 계약 테스트를 추가하세요. 변경되지 않은 입력을 재시도하지 마십시오.

2. 401 인증 오류

키 또는 토큰이 유효하지 않거나, 만료되었거나, 취소되었거나, 잘못 전송되었습니다. 비밀 키 주입 및 프로젝트 환경을 확인하세요. 노출된 키는 교체하고, 디버깅 중에는 절대 출력하지 마세요.

3. 401 잘못된 조직 또는 프로젝트

유효한 키라도 잘못된 범위를 대상으로 할 수 있습니다. 프로젝트 구성과 명시적인 조직/프로젝트 헤더를 확인하세요. 키, 리소스, 결제 범위를 일치시키십시오.

4. 401 IP가 승인되지 않음

요청 출처가 설정된 허용 목록과 일치하지 않습니다. 승인된 이그레스 IP에서 전송하거나, 권한 있는 관리를 통해 허용 목록을 업데이트하세요. 동일한 출처에서 재시도해도 아무 효과가 없습니다.

5. 403 권한 거부 또는 지원되지 않는 리전

호출자가 리소스, 모델 또는 리전에 접근할 수 없습니다. 프로젝트 역할, 모델 가용성, 리소스 소유권 및 지원 국가 규칙을 확인하세요. 내부 로그에서 권한 문제를 "찾을 수 없음"으로 위장하지 마십시오.

6. 404 찾을 수 없음

, 대화, 벡터 저장소, 파일 또는 기타 식별자가 잘못되었거나, 만료되었거나, 접근할 수 없습니다. 정확한 ID와 프로젝트를 확인하세요. 사용자에게 표시되는 경우, 해당 사용자의 범위를 벗어난 리소스의 존재를 노출하지 않도록 주의하세요.

7. 409 충돌

다른 요청이 동시에 리소스를 변경했습니다. 현재 상태를 다시 로드하고, 새 버전에 대해 의도한 변경을 다시 적용한 후, 낙관적 잠금 또는 멱등성을 사용하세요. 무조건적인 즉시 재시도는 충돌을 반복할 수 있습니다.

8. 422 처리할 수 없는 항목

형식은 구문적으로 허용되지만 서비스가 처리할 수 없습니다. 크기, 인코딩, 파일 상태 및 필드 조합을 확인하세요. 공식 테이블은 다시 시도할 것을 제안하지만, 먼저 결정적 원인을 제거하세요.

9. 429 요청 또는 토큰 속도 제한

트래픽 속도를 조절하고 Retry-After가 있을 경우 이를 따르십시오. 그렇지 않으면 지터를 포함한 제한된 지수 백오프를 사용하십시오. 작업자 간에 재시도 예산을 조정하여 썬더링 허드(Thundering Herd)가 발생하지 않도록 하십시오. 중복 호출과 대규모 토큰 버스트를 줄이십시오.

10. 429 slow_down

이것은 램프율 신호입니다: 헤드라인 한도가 충분해 보여도 트래픽이 너무 빠르게 증가한 경우입니다. Retry-After를 따르고, 요청 속도를 줄인 후 점진적으로 늘리십시오. OpenAI의 현재 가이드라인은 분당 백만 개의 입력 토큰에 도달한 후에는 15분마다 최대 50% 이상 증가해서는 안 된다는 경험 법칙을 제시합니다. 실제 활성화는 모델과 조건에 따라 다릅니다.

11. 429 크레딧, 지출 또는 사용량 제한

코드에는 credit_balance_exhausted, organization_spend_limit_exceeded, project_spend_limit_exceeded, organization_usage_limit_exceeded가 포함됩니다. 이는 크레딧 또는 한도 변경이 필요합니다. 재시도로는 접근 권한을 복원할 수 없습니다. 소유자에게 알리고 즉시 실패 처리하세요.

12. 500 내부 서버 오류

잠시 대기 후 제한된 예산으로 재시도하고, 실패가 지속되면 상태 페이지를 확인하세요. 지원을 위해 요청 ID를 기록해 두세요. 상태 변경 워크플로의 경우, 전체 요청을 재실행하기 전에 도구의 부작용을 조정하세요.

13. 503 모델 과부하

문서화된 유형/코드는 service_unavailable_error / server_is_overloaded입니다. Retry-After를 준수하거나, 없을 경우 백오프(back off)하세요. 현재 Python SDK 가이드라인에서는 429의 경우 RateLimitError, 503의 경우 InternalServerError를 구분합니다. 이전에 모든 용량 문제가 429라고 가정하고 과부하 로직을 작성했다면, 두 예외를 모두 처리하세요.

14. 연결 또는 타임아웃 오류

APIConnectionError는 네트워크, 프록시, TLS 인증서, DNS 또는 방화벽 문제를 나타낼 수 있습니다. APITimeoutError는 마감 시간이 경과했음을 의미합니다. 안전한 읽기를 재시도하고, 회사 프록시 설정을 확인하며, TLS 검증을 비활성화하지 마십시오. 쓰기의 경우 재시도 전에 작업이 발생했는지 확인하십시오.

15. 웹소켓 상태 및 스트리밍 실패

previous_response_not_found는 참조된 상태를 확인할 수 없음을 의미합니다. 공식 가이드에 따르면 previous_response_id를 null로 설정하여 전체 입력 컨텍스트를 다시 전송해야 합니다. websocket_connection_limit_reached는 60분 연결 제한을 나타냅니다. 새 연결을 열고 계속 진행하세요. 또한 소켓 종료가 완료를 의미한다고 가정하지 말고 response.failed, response.incomplete 및 전송 error 이벤트를 처리하세요.

재시도 매트릭스

| 클래스 | 재시도 변경 없음? | 올바른 작업 | | 400/401/403/404 | 아니요 | 요청, 신원, 권한 또는 ID 수정 | | 409 | 조정 후 | 버전을 다시 로드하고 안전하게 적용 | | 422 | 때때로 | 결정론적 원인을 먼저 확인하세요 | | 429 rate/slow_down | 예, 제한됨 | Retry-After 준수; 백오프 및 지터 | | 429 청구/한도 | 아니요 | 크레딧을 추가하거나 승인된 한도를 변경하세요 | | 500/503 | 예, 제한됨 | 백오프, 상태 확인, 요청 ID 보존 | | 연결/시간 초과 | 상황에 따라 다름 | 읽기 재시도, 쓰기 조정 |

재시도 횟수 및 총 경과된 재시도 시간. 광범위한 장애 발생 시 회로 차단기를 사용하고, 운영자 검토가 필요한 작업에는 데드 레터 경로를 사용하십시오. 재시도는 관찰 가능해야 하며, 중첩된 SDK 및 애플리케이션 루프 내부에 숨겨져서는 안 됩니다.

자주 묻는 질문

429 오류가 발생할 때마다 재시도해야 하나요?

아니요. 속도 및 램프 오류는 필요한 지연 후 재시도할 수 있습니다. 크레딧, 지출 및 사용량 제한 오류는 계정 조치가 필요합니다.

요청 ID를 기록하는 이유는 무엇인가요?

지원팀과 자체 원격 측정에서 전체 페이로드를 노출하지 않고 특정 API 요청과 실패를 연관시킬 수 있습니다.

시간 초과된 도구 호출을 다시 시도할 수 있나요?

부작용을 일으켰는지 확인한 후에만 재시도하세요. 멱등성 키와 재시도 전 읽기 조정을 사용하세요.

사용자에게 무엇이 표시되어야 하나요?

간결하고 실행 가능한 메시지와 적절한 경우 안전한 재시도 옵션을 제공합니다. 스택 추적, 제공자 코드 및 민감한 세부 정보는 보호된 진단에 보관합니다.

결론

GPT-6 Astra의 안정적인 오류 처리는 분류에서 시작됩니다. 결정론적 4xx 요청을 수정하고, 속도 압력을 청구 한도와 구분하며, 일시적인 5xx 실패를 백오프하고, 불확실한 쓰기를 조정하며, 스트리밍을 상태 기계로 모델링합니다. 제한된 재시도 정책과 우수한 요청 수준 텔레메트리는 무분별한 재시도보다 더 많은 사고를 해결합니다.