문제 해결

오류 형태는 호출한 프로토콜과 일치합니다. /v1/chat/completions 및 /v1/responses 는 OpenAI 스타일의 오류를 반환합니다. /v1/messages 는 Anthropic 스타일의 오류를 반환합니다. HTTP 상태 코드는 세 가지 프로토콜 모두에서 동일합니다.

오류 응답 형식

OpenAI 형식 (/v1/chat/completions, /v1/responses)

{
  "error": {
    "message": "Invalid API key",
    "type": "authentication_error",
    "code": "invalid_api_key"
  }
}

Anthropic 형식 (/v1/messages)

{
  "type": "error",
  "error": {
    "type": "authentication_error",
    "message": "Invalid API key"
  }
}

401 · 인증 실패 authentication_error

{"error":{"message":"missing API key in Authorization header or X-API-Key","type":"authentication_error"}}

원인

• Authorization: Bearer 헤더(또는 X-API-Key)가 없습니다 — 메시지: missing API key in Authorization header or X-API-Key.
• 키가 활성 키와 일치하지 않습니다 — 메시지: invalid API key.
• 키가 만료되었습니다 — 메시지: API key expired.

해결

1. Authorization: Bearer sk-syn-…(또는 X-API-Key: sk-syn-…)를 전송하세요.
2. 콘솔에서 키가 활성 상태이며 전체가 복사되었는지 확인하세요.

400 · 잘못된 요청 invalid_request

{"error":{"message":"model or models field is required","type":"invalid_request"}}

원인

• model 필드가 없거나 JSON 본문이 비어 있거나 형식이 잘못되었습니다.

해결

1. model과 올바른 형식의 JSON 본문을 포함하세요. Chat Completions 참조를 확인하세요.

403 · 할당량 소진 quota_exhausted

{"error":{"message":"API key quota exhausted","type":"quota_exhausted"}}

원인

• 키 또는 워크스페이스의 선불 잔액이 소진되었습니다.

해결

1. 워크스페이스 잔액을 충전하세요. 참고: 잔액이 소진되면 Synthorai는 403 quota_exhausted를 반환하며 429가 아닙니다 — 따라서 지수 백오프는 도움이 되지 않고 충전만이 이를 해제합니다.

403 · 규정 준수 — 데이터 공유 없음 compliance_blocked / compliance_no_data_share

{"error":{"type":"compliance_blocked","code":"compliance_no_data_share","message":"model 'MODEL' is unavailable: your workspace compliance setting disallows providers that retain/train on data"}}

원인

• 워크스페이스에 no_provider_data_share가 활성화되어 있고, 요청한 모델은 데이터 보존/공유를 요구하는 공급자만 제공합니다(예: 데이터 공유 전용 Bedrock 또는 Vertex 모델).

해결

1. 요청을 무보존 모델로 라우팅하거나, 해당 워크로드에서 데이터 공유가 허용된다면 워크스페이스 규정 준수 스위치를 끄세요. 보존 등급은 모델별 라우팅 입력입니다 — 30일 데이터 보존 상세를 참조하세요.

429 · 속도 제한됨 rate_limit_exceeded

{"error":{"message":"rate limit exceeded: max 60 requests per minute","type":"rate_limit_exceeded"}}

원인

• 분당 요청 상한(RPM)을 초과했습니다. 메시지에 정확한 한도가 표시됩니다.

해결

1. 지수 백오프 + 지터로 백오프 후 재시도하세요(아래 스니펫). 지속적인 처리량이 필요하면 한도 상향을 요청하세요.

502 · 모델에 사용 가능한 채널 없음 upstream_error

{"error":{"message":"no channels available for model \"MODEL\" in group \"default\"","type":"upstream_error"}}

원인

• 모델 id가 워크스페이스의 라우팅 가능한 채널과 일치하지 않습니다 — 오타이거나, 목록에서 제거된 모델이거나, 요금제로 접근할 수 없는 모델입니다.

해결

1. 정확한 id를 실시간 모델 목록과 대조하세요. 모델이 최근에 종료되었다면 현재 제공되는 모델을 선택하세요.

BYOK: 업스트림 공급자 오류

bring-your-own-key에서는 요청이 귀하 자신의 공급자 계정(AWS Bedrock, Google Vertex AI 또는 Anthropic API)에서 실행되므로, Synthorai는 공급자의 원본 오류를 그대로 전달합니다 — 응답에는 usage.is_byok: true가 포함됩니다. 해결책은 게이트웨이가 아니라 해당 공급자의 콘솔이나 설정에 있습니다. 가장 흔한 것은 계정 수준의 모델 액세스 및 데이터 공유 설정입니다:

업스트림 공급자 오류

이러한 오류는 모델 공급자로부터 공급자 자체의 HTTP 상태와 type과 함께 전달됩니다. 공급자 측을 나타내는 것은 500과 529뿐이며, 이들(그리고 429)은 일시적인 것으로 간주해 재시도하고, 4xx는 요청 자체를 반영합니다. 전체 참조: Anthropic의 오류 문서.

속도 제한

속도 제한은 API key별로 적용되어 모든 사용자 간 공정한 사용을 보장합니다.

기본 제한

실제 토큰당 가격으로 토큰 처리량을 예산 책정하나요? LLM API 비용 계산기로 워크로드를 실행해 보세요.

429 오류 처리

import time
import openai

client = openai.OpenAI(base_url="https://synthorai.io/v1", api_key="YOUR_API_KEY")

for attempt in range(5):
    try:
        response = client.chat.completions.create(
            model="gpt-5.4-mini",
            messages=[{"role": "user", "content": "Hello"}]
        )
        break
    except openai.RateLimitError as e:
        wait = 2 ** attempt  # exponential backoff
        print(f"Rate limited. Retrying in {wait}s...")
        time.sleep(wait)

async function withRetry(fn, maxAttempts = 5) {
  for (let attempt = 0; attempt < maxAttempts; attempt++) {
    try {
      return await fn();
    } catch (err) {
      if (err.status === 429 && attempt < maxAttempts - 1) {
        const wait = Math.pow(2, attempt) * 1000;
        await new Promise(r => setTimeout(r, wait));
      } else throw err;
    }
  }
}

특정 모델에서 502나 과부하가 발생하나요? 모델 가격 비교에서 대체 모델을 선택하세요 — 모든 라우팅 가능한 모델과 토큰당 가격이 하나의 표에 있습니다.