오류 처리

오류는 요청 단계와 처리 단계로 나눠 확인하세요. 요청 오류가 나면 API가 호출을 받아들이지 않은 거예요. 요청은 접수됐지만 변환 도중 실패하면 작업의 status가 failed로 바뀌어요.

오류 응답 읽기

/v1 API의 요청 오류는 아래 형식으로 반환해요.

{
  "error": {
    "code": "insufficient_minutes",
    "message": "Not enough minutes",
    "retryable": false,
    "action_url": "https://transcript1.com/dashboard/billing",
    "minutes_needed": 20,
    "minutes_remaining": 3
  }
}

코드에서 오류를 분기할 때는 code를 사용하세요. message는 사용자에게 보여 줄 설명이며, 문구가 바뀔 수 있으니 분기 조건으로 쓰지 마세요. retryable이 true이면 잠시 후 같은 요청을 다시 시도할 수 있어요.

오류 종류에 따라 retryable 외에 다음 필드를 함께 반환해요.

요청 단계에서 발생하는 오류

브라우저에서 Bearer 토큰 대신 로그인 쿠키로 인증하면 요청 출처도 검사해요. 다른 사이트에서 보낸 요청에는 403 forbidden_origin을 반환해요. Authorization 헤더로 인증하는 API 호출에는 이 검사를 적용하지 않아요.

429 응답에는 항상 Retry-After 헤더가 있어요. 값은 다시 요청하기까지 기다릴 시간이며 초 단위예요. 실제 한도는 요금제와 사용 한도에서 확인하세요.

안전하게 재시도하기

• 같은 요청을 그대로 다시 보낼 때는 retryable이 true인지 확인하세요. rate_limited, too_many_active_jobs, too_many_live_sessions, live_capacity, internal_error, service_unavailable, 그리고 reason이 pending이나 in_progress인 topup_needs_user가 해당해요. Retry-After가 있으면 지정한 시간만큼 기다리고, 없으면 재시도 간격을 늘리세요.
• POST /v1/transcriptions나 POST /v1/topups를 다시 보낼 때는 처음과 같은 Idempotency-Key 헤더를 사용하세요. 첫 요청이 이미 성공했더라도 중복 차감을 막을 수 있어요.
• 다른 오류는 원인을 해결하고 요청을 수정한 뒤 다시 보내세요.

실시간 변환

POST /v1/live/sessions와 다른 실시간 엔드포인트도 같은 오류 응답 형식을 써요. 위 표의 실시간 코드와 함께 invalid_request, unsupported_language, insufficient_minutes, email_not_verified도 해당해요. 세션 생성은 멱등하지 않기 때문에 too_many_live_sessions나 live_capacity 뒤에 다시 보내면 새 세션이 만들어져요.

세션이 만들어진 뒤의 문제는 HTTP 오류가 아니라 WebSocket의 error 이벤트와 종료 코드로 전달돼요. 모든 이벤트는 실시간 변환을 참고하세요.

balance_exhausted나 idle_timeout 같은 사유로 끝난 실시간 세션은 오류가 아니에요. 종료 사유와 함께 session.ended가 전달되고 세션은 저장돼요. 종료 사유를 참고하세요.

접수된 작업이 실패한 경우

작업의 status가 failed이면 객체에 error: { "code", "message" }가 들어 있어요. 생성 요청에 응답한 뒤에도 작업이 실패할 수 있어요. 상태를 조회할 때 error를 확인하거나 transcription.failed 웹훅에서 원인을 읽으세요. 번역이 실패하면 transcription.translation.failed 웹훅이 전송되며, 이 때문에 전사가 실패하는 일은 없습니다.

작업이 실패하거나 취소되면 비용이 들지 않아요. 이미 차감한 분량은 돌려드려요.