오류

Reigniter API은 표준 HTTP 상태 코드를 사용합니다. 모든 오류 응답은 JSON입니다.

오류 본체

대부분의 오류는 다음과 같습니다:

{
  "error": "Rate limit exceeded",
  "code": "RATE_LIMITED",
  "retryAfter": 37
}

필드	항상 존재한다	무엇인가
`error`	네	사람에게 보여줄 수 있는 메시지. 문구가 바뀔 수 있으니 일치하지 마세요.
`code`	대부분의 오류	안정적이고 대문자 코드야. 이걸로 분기해.
`details`	몇 가지 오류	예를 들어 `retryAfter` 이나 사용량 수치와 같은 추가 맥락.
`retryAfter`	몇몇 `429`	재시도하기 전에 몇 초만 기다릴 수 있다.

404 Job not found와 403 Forbidden 같은 몇몇 오류는 code가 없습니다. 그 오류들은 상태를 분기하세요.

검증 오류

요청 본문이 스키마와 일치하지 않을 때, 모든 문제를 다음과 같이 나열하는 detail 문자열로 400``field: message:

{
  "error": "Validation failed",
  "detail": "aspect: Invalid option: expected one of \"9:16\"|\"16:9\"|\"1:1\"|\"4:5\"|\"4:3\"|\"3:4\""
}

상태 코드

현황	의미	어떻게 해야 할까요
`200`	성공.
`201`	생성(웹훅).
`202`	수락. 렌더링이 시작되었습니다.	일자리를 폴링하거나 웹훅을 기다리세요.
`400`	그 요청은 거부되었습니다. 아무런 혐의도 받지 않았습니다.	요청을 수정하세요. 변경 없이 다시 시도하지 마세요.
`401`	API 키가 분실되었거나, 무효 또는 취소되었습니다.	열쇠를 확인해.
`402`	요금제, 신용 또는 사용 문제.	읽어 `code`.
`403`	계정이 정지되었거나, 본인과 다른 직장을 맡았을 수도 있습니다.	지원팀에 연락하거나 채용 ID를 확인하세요.
`404`	찾지 못했습니다.	ID나 경로를 확인하세요.
`409`	중복 요청 또는 한도 초과.	읽어 `code`.
`413`	이 렌더링은 렌더링당 한도를 초과할 것입니다.	장면 수를 줄이거나 `quality`을 낮추세요.
`422`	렌더링에는 브랜드, 제품, 발표자가 없어 고정 요소가 없습니다.	영상 만들기를 참고하세요.
`429`	요청이 너무 많거나 한 번에 렌더링이 너무 많아요.	기다렸다가 다시 시도하세요. 한계를 참조하세요.
`500`	우리 쪽에서 뭔가 잘못됐어.	나중에 다시 시도하세요.
`502`	당신의 브리핑 계획이 실패했습니다. 계획 학점은 환불되었습니다.	다시 시도하거나 브리핑을 다시 작성하세요.
`503`	제공이 일시정지되거나 서비스가 중단된 상태입니다. 아무런 요금도 청구되지 않았습니다.	나중에 다시 시도하세요.

/v1/ 아래의 미지의 경로가 code: "NOT_FOUND"와 함께 404 돌아옵니다.

오류 코드

인증 및 계획

코드	현황	의미
`NO_API_KEY`	401	`Authorization` 헤더가 없거나, 토큰이 `emp_`로 시작하지 않습니다.
`INVALID_API_KEY`	401	열쇠는 알려지지 않았거나 취소되었습니다.
`PLAN_UPGRADE_REQUIRED`	402	API 접근은 Agency 계획이 필요합니다.
`ACCOUNT_SUSPENDED`	403	계정이 정지되었습니다.

크레딧 및 사용

코드	현황	의미
`NO_CREDITS`	402	계좌에 남아 있는 크레딧이 없습니다.
`INSUFFICIENT_CREDITS`	402	이 렌더링에는 크레딧이 부족하다.
`ABUSE_CAP_EXCEEDED`	402	요금제의 월간 사용 한도에 도달했습니다.
`STORAGE_FULL`	402	계정의 동영상 라이브러리가 가득 찼습니다. 일부 동영상을 삭제하세요.
`UPGRADE_REQUIRED`	402	비디오는 유료 요금제가 필요합니다.
`REQUEST_COST_TOO_HIGH`	413	이 한 번의 렌더링은 렌더링당 한도를 초과할 것입니다.

크레딧과 플랜에 대해서는 계정 및 청구 항목을 참조하세요.

렌더 요청

코드	현황	의미
`CONTENT_BLOCKED`	400	브리프나 장면은 콘텐츠 규칙을 어깁니다.
`PRODUCT_IMAGE_REQUIRED`	400	이 형식은 `product_image_url`, 또는 `product_enabled: false` 필요합니다.
`PRESENTER_REQUIRED`	400	대화 장면에는 얼굴이 없습니다. `avatar_preset_id` 추가하거나 보내 `presenter_enabled: false`.
`UNSUPPORTED_MODEL`	400	렌더링 모델을 요청한 장면이 Reigniter 사용할 수 없습니다.
`BRAND_REQUIRED`	422	브랜드를 요청했지만 찾을 수 없었다. 보내 `brand_logo_url`.
`NO_ANCHOR`	422	브랜드, 제품 사진, 발표자는 없고요. 하나만 추가하거나 선택하지 마세요.
`CANVAS_NOT_FOUND`	404	참고된 프로젝트는 이 계정에 포함되어 있지 않습니다.
`DUPLICATE_REQUEST`	409	이 `Idempotency-Key` 은 이미 사용된 상태였다. 새로운 혐의는 없었다.
`PLAN_FAILED`	502	브리핑에서 계획이 실패했습니다. 계획 학점은 환불되었습니다.

brief의 경우 반복된 Idempotency-Key도 메시지와 함께 402 This request was already submitted 응답할 수 있습니다. 이를 중복으로 간주하고 신용 문제로 간주하지 마세요.

속도와 동시성

코드	현황	의미
`RATE_LIMITED`	429	요청이 너무 많아요. `retryAfter` 초(또는 `details.retryAfter`초)만 기다려보세요.
`CONCURRENT_LIMIT`	429	한 번에 너무 많은 렌더링이 실행되고 있습니다. 하나가 끝날 때까지 기다리세요.

운용

코드	현황	의미
`USAGE_CHECK_UNAVAILABLE`	503	사용량을 확인할 수 없어 렌더링이 일시정지되었습니다. 요금은 부과되지 않았습니다.
`DB_UNAVAILABLE`	503	잠시 서비스가 불가합니다.
`FEATURE_NOT_AVAILABLE`	503	현재 렌더링은 불가능합니다.
`GLOBAL_KILL_SWITCH`	503	렌더링은 모두에게 일시정지되어 있습니다.
`FEATURE_KILL_SWITCH`	503	이 기능은 일시정지되어 있습니다.
`USER_KILL_SWITCH`	503	이 계정은 일시적으로 제한되어 있습니다. 고객 지원에 연락하세요.

웹훅

코드	현황	의미
`UNKNOWN_EVENT`	400	구독할 수 있는 이벤트가 아닙니다. 답변에는 유효한 이벤트들이 나열되어 있습니다.
`URL_NOT_DELIVERABLE`	400	URL은 공개 http(s) 주소가 아닙니다.
`HOOK_LIMIT`	409	계정은 이미 최대 수의 웹훅을 보유하고 있습니다.

안전하게 재도전하기

백오프를 429, 500, 502, 503 다시 시도하세요. 변경 없이 다른 4xx 다시 시도하지 마세요.
항상 Idempotency-Key 보내 POST /v1/render.
응답이 전혀 없 고(타임아웃 또는 연결 끊김): 같은 키로 재시도하세요. 첫 번째 요청이 렌더를 시작했다면, 두 번째 요청을 시작하는 대신 재시도가 거부됩니다.
오류 응답: 해당 요청에 대해 렌더링이 시작되지 않았습니다. 원인을 수정한 후 새 키로 다시 시도하세요. 중간에 실패한 요청이 이미 키를 사용했을 수도 있기 때문입니다. 렌더 크레딧은 환불됩니다. 환불되지 않는 유일한 비용은 계획된 렌더링이 거부될 때 간단히 계획하는 것입니다(비디오 만들기) 참고.
렌더링이 수락되었고(202) 나중에 실패하면, 작업 status 가 failed 되고 error 이유를 설명합니다. 일하지 않은 작업에 대한 크레딧은 환불됩니다.