오류 처리

오류는 요청 단계와 처리 단계로 나눠 확인하세요. 요청 오류가 나면 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, internal_error, service_unavailable이 해당해요. Retry-After가 있으면 지정한 시간만큼 기다리고, 없으면 재시도 간격을 늘리세요.
• POST /v1/transcriptions를 다시 보낼 때는 처음과 같은 Idempotency-Key 헤더를 사용하세요. 첫 요청이 이미 성공했더라도 중복 차감을 막을 수 있어요.
• 다른 오류는 원인을 해결하고 요청을 수정한 뒤 다시 보내세요.

접수된 작업이 실패한 경우

작업의 status가 failed이면 객체에 error: { "code", "message" }가 들어 있어요. 생성 요청에 응답한 뒤에도 작업이 실패할 수 있어요. 상태를 조회할 때 error를 확인하거나 transcription.failed 웹훅에서 원인을 읽으세요.

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