API 에러 코드
System One API 오류 구조, 상태 코드, TypeScript SDK에서의 처리.
System One API는 일관된 오류 봉투와 안정적인 분류 헤더를 사용합니다. 메시지 문구를 매칭하거나 본문 구조를 가정하지 말고 문서화된 헤더로 오류를 분류하세요. 이 페이지는 HTTP API와 콘솔 엔드포인트에서 오류를 다룰 때와 System One SDK를 통합할 때 사용합니다.
저장해 둘 값
HTTP 상태, X-System-One-Error-Code, X-Request-Id, 요청 시각을 저장하세요. API 키, Authorization 헤더, 민감한 요청 내용은 로그에 남기지 마세요.
오류 출처 구분하기
X-System-One-Error-Source를 X-System-One-Error-Code와 함께 읽으세요.
platform: System One 오류입니다. JSON 봉투에error.code가 들어 있습니다.upstream: 유효한 모델 서비스 JSON 오류가 원래 HTTP 상태(400–599)와 본문 그대로 전달됩니다. 본문은 객체, 배열, 문자열, 다른 JSON 스칼라, null일 수 있으며 System One 봉투 형식이 아닐 수 있습니다.
안정적인 헤더 분류는 업스트림 HTTP 429/529를 provider_busy, 400/422를 provider_rejected_request, 그 외 업스트림 실패를 provider_unavailable로 나눕니다. 업스트림 401/403은 그대로 401/403이며 호출자의 System One 로그인이 만료되었다는 뜻이 아닙니다.
Retry-After는 초 단위 값이나 HTTP 날짜일 수 있습니다. 임의의 message나 detail 텍스트를 그대로 표시하지 말고 안정적인 분류로 메시지를 만들세요. 오류 본문이 민감한 입력을 되돌릴 수 있습니다.
System One 오류 봉투
X-System-One-Error-Source: platform이 System One 오류와 안전 대체 응답을 식별합니다. 값은 예시이며 다음과 같은 형태입니다.
{
"error": {
"code": "insufficient_credits",
"message": "This request requires 3 credits. Top up your account to continue.",
"request_id": "example-request-id"
},
"request_id": "example-request-id"
}지원과 정산에는 본문의 임의 필드가 아니라 X-Request-Id에서 요청 ID를 읽으세요. provider_* 오류는 모델 요청 완료를 위한 문제이며, HTTP 401이나 403이더라도 System One 키나 브라우저 로그인이 만료되었다는 뜻은 아닙니다.
상태 코드와 코드
| HTTP | 코드 | 의미 |
|---|---|---|
| 400 | invalid_json | 유효하지 않거나 모호한 JSON, 잘못된 UTF-8, 중복 객체 키. |
| 401 | invalid_api_key | Bearer 키가 없거나 잘못됨, 폐기됨. |
| 401 | unauthorized | 인증된 계정 또는 세션이 필요한 엔드포인트. |
| 402 | insufficient_credits | 계정이 이 요청의 크레딧을 예약할 수 없음. |
| 403 | account_disabled | 플랫폼 계정이 비활성화됨. |
| 409 | idempotency_conflict | 같은 키에 다른 본문이 사용됨. |
| 409 | request_in_progress | 같은 작업이 아직 처리 중. Retry-After를 따르세요. |
| 409 | idempotency_failed | 이전 시도가 실패하고 크레딧이 반환됨. |
| 409 | request_expired | 중간에 예약이 만료됨. |
| 410 | idempotency_expired | 재플레이 데이터가 만료됨. |
| 413 | request_too_large | 요청이 UTF-8 바이트 한도를 초과함. |
| 415 | unsupported_media_type | Content-Type이 application/json이 아님. |
| 422 | invalid_request | 잘못된 필드, 모델 한도 위반, 지원하지 않는 확장 필드. |
| 422 | invalid_idempotency_key | Idempotency-Key 형식이 잘못됨. |
| 422 | unsupported_model | 지원하지 않는 모델. |
| 429 | rate_limit_exceeded | 플랫폼 할당량 소진 또는 제공자가 바쁨. |
| 499 | request_cancelled | 호출자가 요청을 취소함. |
| 500 | internal_error | 예상치 못한 플랫폼 오류. |
| 501 | model_listing_not_supported | 이 연결에서 모델 목록을 사용할 수 없음. |
| 502 | invalid_provider_response | 모델 응답이 잘못되었거나 1MB를 초과함, JSON이 아님, 리디렉션임. |
| 503 | provider_not_configured | 제공자 설정이 필요함. |
| 503 | request_reconciliation_pending | 요청의 과금이 아직 확정되지 않음. X-System-One-Credits가 생략됩니다. |
| 504 | provider_timeout | 공유 20초 기한을 초과함. |
인증과 초기 요청 검증 실패는 새 의사결정 예약 전에 발생하므로 의사결정 크레딧을 소모하지 않습니다.
재시도 전 과금 확인하기
일반적인 실패 평가에서는 해당 시도에 차감된 크레딧이 반환됩니다. X-System-One-Credits: 0은 그 시도에서 유지된 차금이 없음을 확인합니다. 즉시 정산할 수 없으면 서비스는 request_reconciliation_pending를 반환하고 이 헤더를 생략합니다. 누락된 차감 헤더는 0을 의미하지 않습니다. 콘솔 사용 기록을 확인하세요.
클라이언트 타임아웃이나 연결 끊김은 작업이 실패했다는 증거가 아닙니다. 같은 작업 키와 요청 본문으로 복구하세요. 실패와 환불이 확인된 뒤에만 새 키로 새 시도를 시작하세요.
SDK에서 오류 처리하기
core 0.8.0의 APIError는 statusCode, requestId, retryAfterMs를 제공하지만 서버 오류 본문 전체나 분류 헤더는 제공하지 않습니다. 서로 다른 409 코드를 구분해야 한다면 Fetch를 사용하세요. 독립 유지보수되는 공식 @typesafe-ai/sdk@0.6.0은 자체 오류 클래스를 가지며, 두 클라이언트가 같은 형태를 노출한다고 가정하지 마세요.
클라이언트 재시도 정책은 서비스와 별개이며, 서비스는 모델 추론을 자동으로 재시도하지 않습니다. 응답이 불확실한 뒤에는 보관한 키와 본문으로 복구하세요.
해결되지 않은 오류나 과금은 support@system-one.dev로 요청 ID, 시각, 상태, 오류 코드를 함께 보내세요. API 키나 민감한 제출 내용은 보내지 마세요.
자주 묻는 질문
Q: System One API의 오류 처리는 어떻게 동작하나요? A: 일관된 오류 봉투와 HTTP 상태 코드를 사용하고, TypeScript SDK는 타입이 있는 오류를 제공합니다. 적절한 경우 멱등 키로 재시도하세요.