에러 (Errors)

모든 SDK 에러는 추상 클래스 OpenEchoError를 상속하며, 서버 wire 코드(err.code)와 err.httpStatus·err.message를 항상 보존합니다.

import {
  OpenEchoError, CapabilityDenied, UsageCapExceeded, OriginForbidden,
} from "@openecho/partner-sdk";

try {
  await oe.broadcast.tts.send({ /* ... */ });
} catch (err) {
  if (err instanceof CapabilityDenied) {
    // TTS capability 미허가
  } else if (err instanceof UsageCapExceeded) {
    // 일일 quota 초과
  } else if (err instanceof OpenEchoError) {
    console.error(err.code, err.httpStatus, err.message);
  }
}

서버 wire 에러 (14)

서버 wire 코드와 SDK 에러 클래스의 완전한 대응입니다. HTTP 상태는 대표값이며, 실제 값은 서버 응답을 그대로 보존합니다.

클라이언트 측 에러 (3)

다음 세 에러는 서버 wire 코드가 아니라 클라이언트/transport 계층에서 발생하므로 wire 표에 없습니다.

멱등성 키

idempotencyKey는 중복 방송을 막는 클라이언트 생성 키입니다.

• 새 방송마다 crypto.randomUUID()로 고유 키를 생성합니다.
• 네트워크 오류로 재시도할 때는 동일한 키를 재사용합니다(서버가 멱등 처리).
• 다른 페이로드에 같은 키를 재사용하면 IdempotencyKeyReused(409)가 발생합니다.

Quota · Rate Limit

파트너 앱별 일일 TTS 한도 초과 시 UsageCapExceeded(429)가 발생하며 다음 날 자정(UTC)에 초기화됩니다. 단시간 과도 요청은 RateLimited(429) — 지수 백오프로 재시도합니다. RateLimitBackendUnavailable(503)은 잠시 후 재시도합니다.

Origin 잠금 진단

도메인 잠금(OriginForbidden)은 두 단계로 확인합니다.

1. 브라우저 CORS 차단 — 미등록 origin은 preflight에서 차단됩니다. DevTools → Network에서 CORS error 확인. 해결: 관리 콘솔에서 origin 추가.
2. curl로 wire error 확인 — CORS를 우회해 실제 error.code를 확인합니다.

curl -s -X POST "https://your-openecho-api.example.com/api/partner/v1/broadcasts/tts" \
  -H "X-OpenEcho-Key: pk_test_..." \
  -H "Content-Type: application/json" \
  -H "Origin: https://not-registered.example.com" \
  -d '{"targetHandle":"grp_main","text":"test","language":"ko","idempotencyKey":"k","partial":false}'

Unauthorized(키 오류)와 OriginForbidden(도메인 잠금)은 별개입니다. 응답 error.code로 정확히 구분하세요.

CloudFront /api 마스킹 주의

dev 환경에서 CloudFront는 /api/* 4xx를 SPA index.html(HTTP 200)로 치환할 수 있습니다. 이때 SDK는 null 대신 명시적으로 throw합니다.

• 2xx + HTML → GatewayMasked
• 2xx + 비-JSON → InvalidApiResponse