Text-to-Video API 오류 코드 완벽 정리

text-to-video API 오류 코드 가이드 — 400/401/403/429 및 5xx, 안전 차단, 비동기 작업 실패, 재시도, 단계별 디버깅 워크플로.

튜토리얼

대부분의 text-to-video API 실패는 5가지 유형으로 정리됩니다: 잘못된 요청, 인증 문제, 속도 제한, 안전 차단, 또는 서버 문제. HTTP 상태 코드, 전체 오류 본문, 요청 또는 작업 ID, 그리고 실패 시각을 확인하면 보통 원인을 빠르게 찾을 수 있습니다.

간단히 정리하면 다음과 같습니다:

400 계열 오류는 대개 요청을 수정해야 한다는 뜻입니다.
401/403은 대개 API 키, 접근 권한, 결제, 또는 IP 규칙을 가리킵니다.
429는 요청, 작업, 또는 지출 한도에 도달했다는 의미입니다.
제출 시 200 OK가 나와도 영상이 완성된 것은 아닙니다. 여전히 작업을 폴링하고 failed 여부를 확인해야 합니다.
500 계열 오류는 재시도가 필요한 경우가 많지만, 작업이 아직 실행 중인지 먼저 확인한 후에 재시도해야 합니다.
안전 차단은 생성 전, 생성 중, 또는 생성 후에 발생할 수 있으며, 일부 API는 전체 작업을 실패시키는 대신 클립 수를 줄여서 반환하기도 합니다.

몇 가지 수치가 눈에 띕니다. Sora 2를 사용하는 것과 같은 영상 작업은 GPU를 30~90초 동안 점유할 수 있고, 클라이언트 타임아웃은 10분 이상 필요할 수 있으며, 일반적인 재시도 계획은 5초에서 시작, 60초에서 상한, 3회 시도 후 중단입니다.

실패한 작업과 중복 청구를 줄이고 싶다면 워크플로를 간단하게 유지합니다:

오류 본문과 작업 ID를 로깅
API 계층 오류와 작업 수준 실패를 구분
429와 5xx의 경우에만 재시도
같은 작업을 다시 제출하기 전에 작업 상태를 확인
latest 같은 별칭 대신 정확한 모델 버전을 고정

우수한 개발자 경험을 위한 API 오류 메시지

빠른 비교

오류 그룹	일반 코드	보통 무엇을 의미하는가	재시도?	첫 조치
검증	400, 404, 413, 415, 422	잘못된 JSON, 잘못된 모델 ID, 파일이 너무 큼, 잘못된 형식, 필드 충돌	아니오	요청 수정
고품질 영상	Veo 3.1	전문적인 시네마틱 출력	예	프롬프트 파라미터 확인
인증 / 접근	401, 403	잘못된 키, 누락된 스코프, 크레딧 없음, 차단된 IP	아니오	키, 결제, 스코프 확인
속도 제한	429	너무 많은 요청, 너무 많은 실행 중인 작업, 지출 한도 도달	예	백오프 후 한도 검토
안전 / 정책	400, 403, 또는 작업 수준 실패	프롬프트 또는 출력이 차단됨	아니오	프롬프트 재작성
서버 / 게이트웨이	500, 502, 503, 504	제공자 오류, 과부하, 타임아웃	예	작업 상태 확인 후 재시도

간단히 말하면, 제출 성공은 렌더링 성공이 아닙니다. 폴링 결과를 신뢰의 원천으로 삼고, 상태 코드뿐만 아니라 오류 페이로드를 활용해 다음에 무엇을 할지 결정하는 것이 좋습니다.

클라이언트 측 요청 오류: 수정 가능한 400 계열 코드

오류 세부 정보를 로깅한 후 다음 단계는 요청 측에서 무엇이 잘못되었는지 파악하는 것입니다. 오류 본문부터 시작한 다음, HTTP 코드를 해결책에 매핑합니다.

400, 404, 413, 415: 각 코드가 영상 요청에 의미하는 것

각 코드는 서로 다른 종류의 요청 실수를 가리킵니다. 400은 보통 잘못된 JSON, 필수 필드 누락, 또는 잘못된 파라미터 타입을 의미합니다. 예를 들어 duration을 정수(6) 대신 문자열("6")로 전달하면 검증에 실패합니다 ^[4]. 404는 모델 ID나 엔드포인트 경로가 잘못되었다는 뜻으로, [wan-2.7](https://apimart.ai/ja/model/wan-2-7) 또는 [wan-2.6](https://apimart.ai/model/wan-2-6) 대신 wan2.7처럼 작은 오타 때문인 경우가 많습니다 ^[7]. 413은 참조 이미지나 영상이 업로드 크기 제한보다 클 때 나타납니다 ^[4]^[7]. 415는 Content-Type 헤더가 잘못되었거나 파일 형식이 모델에서 지원되지 않는다는 의미입니다 ^[5].

HTTP 코드	일반적인 Text-to-Video 원인	직접적인 해결책
400	잘못된 JSON; `duration`이 문자열로 전달됨; 필수 필드 누락	숫자 값에서 따옴표 제거; JSON 문법 검증; 누락된 필드 추가
404	철자가 틀렸거나 더 이상 사용되지 않는 모델 ID	문서에서 정확한 모델 문자열 확인 (예: `kling-3.0-turbo`)
413	참조 이미지나 영상이 업로드 크기 제한 초과	에셋 압축 또는 Base64에서 URL 참조로 전환
415	잘못된 `Content-Type` 헤더 또는 지원되지 않는 파일 형식	`Content-Type: application/json` 설정; 에셋을 지원되는 형식으로 변환

검증 실패를 유발하는 모델 및 파라미터 불일치

JSON이 깔끔하더라도 모델마다 규칙이 다르기 때문에 요청이 여전히 검증에 실패할 수 있습니다. 해상도, 길이, 화면 비율, 에셋 제한은 모델에 따라 달라질 수 있습니다.

MiniMax-Hailuo-2.3을 예로 들어보겠습니다. 768p에서 10초를 지원하지만, 1080p를 요청하면 최대 길이가 6초로 줄어듭니다 ^[6]. 에셋 규칙도 그만큼 엄격할 수 있습니다. Kling 3.0은 입력 이미지가 양쪽 차원 모두 최소 300px이어야 하며, 화면 비율이 1:2.5에서 2.5:1 사이여야 합니다. Wan 2.7은 참조 영상이 2~10초 길이여야 하고 100MB를 넘지 않아야 합니다 ^[4]^[7].

422는 보통 파라미터끼리 충돌한다는 의미입니다. 예를 들어 SkyReels V4는 같은 요청에 Image-to-Video와 Omni 필드를 함께 사용하면 422를 반환합니다 ^[8].

작은 습관 하나가 많은 시간을 절약할 수 있습니다: 일반적인 별칭 대신 고정된 버전 문자열을 사용하세요. 파라미터 규칙은 모델 버전 간에 바뀔 수 있습니다 ^[3]. 검증이 계속 실패하면 재시도하기 전에 모델의 정확한 제한을 확인하세요.

요청은 검증을 통과했지만 여전히 실패한다면, 다음으로 인증, 속도 제한, 안전 검사로 넘어갑니다.

인증, 권한, 속도 제한

검증을 통과하고 나면 남은 실패 대부분은 세 가지로 정리됩니다: 인증, 권한, 또는 속도 제한.

401과 403: API 키 및 접근 오류

401 Unauthorized 오류는 요청에 유효한 인증 자격 증명이 포함되지 않았다는 의미입니다. 일반적인 원인은 API 키 누락, 잘못된 키, 비활성화되거나 삭제된 키, 또는 손상된 Authorization 헤더입니다 ^[9]^[1]^[2].

많은 API는 다음을 기대합니다:

Authorization: Bearer YOUR_API_KEY

일부 플랫폼은 대신 x-api-key를 사용합니다. 따라서 헤더 이름이나 형식이 어긋나면 그것만으로도 401이 발생할 수 있습니다 ^[1]^[10].

기본부터 시작하세요. 환경 변수를 확인하고, 키가 아직 활성 상태인지 확인하며, CI/CD 설정이 각 환경에 시크릿을 올바르게 주입하는지 확인합니다 ^[3]. 또한 HTTP 상태 코드에서 멈추지 말고 응답 본문을 읽는 것이 도움이 됩니다. invalid_api_key, token_expired, account_banned 같은 오류는 보통 무엇이 잘못되었는지 훨씬 빠르게 알려줍니다 ^[9]^[3].

403 Forbidden은 서버가 당신을 인식했지만 여전히 요청을 차단했다는 의미입니다. 이는 보통 접근 문제를 가리킵니다. 키에 올바른 모델 스코프가 없거나, 계정 요금제에 해당 엔드포인트가 포함되지 않았거나, 크레딧이 소진되었거나, 요청 IP가 허용 목록에 없을 수 있습니다 ^[3]^[9].

여기서도 응답 본문이 중요합니다. insufficient_credits가 보이면 결제를 확인하세요. permission_error가 보이면 스코프, 모델 접근 권한, 또는 요금제 제한을 확인하세요. 접근에는 문제가 없어 보이는데 트래픽이 너무 많다면, 다음 단계는 보통 429입니다.

429: 속도 제한 및 할당량 초과 오류

인증이 성공하면 요청량이 다음 병목이 되는 경우가 많습니다. 429 Too Many Requests 오류는 스로틀, 동시성 한도, 또는 지출 한도에 도달했다는 의미입니다 ^[3]^[9]^[10]. 쉽게 말해, 짧은 시간에 너무 많은 요청을 보냈거나, 한 번에 너무 많은 작업을 실행했거나, 결제 한도를 넘은 것입니다 ^[3]^[9].

역시 응답 본문이 가장 좋은 단서를 줍니다. rate_limit_exceeded는 보통 지수 백오프를 사용해야 한다는 의미입니다. spend_limit_exceeded는 결제 설정을 확인할 때가 되었다는 뜻입니다 ^[3]^[9].

가능하면 배치 작업을 로컬에서 큐잉하고, 다음 헤더를 주시하세요 ^[2]:

X-RateLimit-Limit
X-RateLimit-Remaining
X-RateLimit-Reset

상태 코드	일반적인 원인	전형적인 응답 패턴	권장 해결책
401 Unauthorized	API 키 누락 또는 무효; 잘못된 `Authorization` 헤더	`invalid_api_key`, `Missing Authorization header`	환경 변수 확인; `Bearer` 접두사 확인; 키가 취소되지 않았는지 확인
403 Forbidden	권한 부족; 키에 모델 스코프 없음; IP가 허용 목록에 없음	`permission_error`, `insufficient_credits`, `ip_not_allowed`	결제, 모델 접근 스코프, 계정 요금제, 또는 IP 허용 목록 확인
429 Too Many Requests	속도 제한, 동시성 제한, 또는 지출 한도 도달	`rate_limit_exceeded`, `spend_limit_exceeded`, `too many running jobs`	지수 백오프 사용; 요청 큐잉 추가; 할당량 또는 결제 한도 검토

APIMart를 사용한다면, 여러 모델에 걸친 단일 키가 인증 편차를 줄일 수 있습니다 ^[3]. 그렇더라도 디버깅 흐름은 거의 동일하게 유지됩니다: 응답 본문을 읽고, 환경 변수를 확인하고, 계정이 호출하려는 모델에 접근할 수 있는지 확인하세요.

안전 차단, 타임아웃, 서버 측 실패

요청 검증과 인증을 통과한 후 남는 실패는 보통 두 가지 유형으로 나뉩니다: 모더레이션 차단과 서버 측 문제. 따라서 인증, 할당량, 검증이 해결되면 나머지 디버깅을 이 두 경로로 나눕니다.

영상 생성에서의 모더레이션 및 콘텐츠 정책 오류

안전 차단은 세 가지 다른 지점에서 발생할 수 있습니다: 생성이 시작되기 전 (요청이 즉시 거부됨), 렌더링 중 (작업이 중간에 중단됨), 또는 영상이 생성된 후 (출력이 전달 전에 필터링됨) ^[11]. 마지막 경우가 사람들을 혼란스럽게 합니다. 작업이 완료되어도 결과가 필터링되면 아무것도 전달되지 않을 수 있습니다.

폴링 기반 API에서는 HTTP 상태가 오해를 불러올 수 있습니다. 상태 확인에서 200 OK를 받았는데, JSON 본문에는 state: "failed"가 있고 SensitiveContentDetected나 NSFW 같은 오류가 포함될 수 있습니다 ^[12]. 실제로 폴링 본문이 신뢰의 원천이며, HTTP 상태 코드가 아닙니다.

모더레이션 차단이 발생하면 똑같은 프롬프트를 재시도하지 마세요. 다시 작성하세요. 평이하고 기술적인 촬영 용어는 엄격한 안전 필터의 오탐을 줄이는 데 도움이 될 수 있습니다 ^[11]. 예를 들면:

gimbal shot
medium tracking shot
golden hour lighting

여기에 또 다른 변수가 있습니다. Google Veo를 포함한 일부 모델은 일부 출력이 안전 필터에 의해 차단되면 전체 작업을 실패시키는 대신 요청한 것보다 적은 수의 클립을 반환할 수 있습니다 ^[3]. 따라서 요청이 완료되었는지만 확인하지 마세요. 반환된 에셋 수가 요청한 수와 일치하는지 확인하세요.

프롬프트가 깨끗해 보이는데도 작업이 계속 실패하면, 다음 계층인 서버 안정성으로 넘어갑니다.

비동기 영상 작업의 500, 502, 503 및 타임아웃 오류

서버 측 실패는 디버깅 흐름의 다른 부분에 위치합니다. Text-to-video 작업은 종종 GPU 슬롯을 30~90초 동안 점유하며 ^[3], 이로 인해 과부하와 타임아웃에 더 민감해집니다.

500과 504 오류의 경우, 재시도하기 전에 작업 상태를 확인하세요. 무분별한 재시도는 중복 렌더링을 만들고 비용을 두 배로 늘릴 수 있습니다 ^[3]. 모든 taskId나 prediction_id를 로깅해 두면 새 작업을 제출하기 전에 상태 엔드포인트를 직접 조회할 수 있습니다 ^[3]^[13].

재시도가 안전할 때는 지터를 포함한 지수 백오프를 사용하세요. 실용적인 설정은 다음과 같습니다:

5초에서 시작
60초에서 상한
3회 시도 후 중단 ^[13]^[12]

오류 코드	유력한 원인	재시도 지침
500 Internal Server Error	예기치 않은 서버 측 실패	먼저 작업 상태 확인; 백오프와 함께 최대 3회 재시도 ^[3]^[12]
502 Bad Gateway	업스트림 제공자 오류	지수 백오프와 함께 재시도 ^[12]
503 Service Unavailable	플랫폼 과부하 또는 유지보수	30~120분 대기 후 상태 대시보드 확인 ^[3]^[12]
504 Gateway Timeout	제공자가 제때 응답하지 않음	재제출 전에 렌더링이 아직 처리 중이 아닌지 확인 ^[3]

클라이언트 타임아웃을 10분 이상으로 설정하고 ^[3], 상승하는 predict_time 값에 대해 알림을 설정하세요 ^[3].

Text-to-Video API를 위한 단계별 디버깅 워크플로

오류를 분류한 다음 올바른 해결책을 적용하세요

이 워크플로를 사용하면 증상에서 해결책까지 한 번에 갈 수 있습니다. 먼저 전체 응답 본문을 읽으세요. 그런 다음 HTTP 상태 코드와 오류 본문이 말하는 내용으로 실패를 분류합니다. 일부 제공자는 내부 오류 범위도 함께 보내지만, 주요 기준은 HTTP 상태 코드와 오류 본문이어야 합니다 ^[3]^[1].

응답 본문부터 시작한 다음, 결과를 다음 그룹 중 하나에 배치하세요:

오류 범주	HTTP 코드	재시도?	첫 조치
인증	401, 403	아니오	환경 변수에서 API 키 확인; 결제/할당량 확인
검증	400	아니오	요청 수정 - JSON 문법, 해상도, 파일 형식, 또는 길이
속도 제한	429	예	지수 백오프 사용; 동시성 한도 확인
안전/정책	400, 403	아니오	프롬프트 재작성; 변경 없이 재시도하지 말 것
서버/게이트웨이	500, 502, 503, 504	예, 작업 상태 확인 후	재제출 전에 작업 상태 확인

작업이 제출된 후에는 HTTP 응답만으로 생각하지 말고 작업 상태도 함께 살펴보세요. 비동기 작업의 경우, 같은 작업을 다시 보내기 전에 폴링 응답에서 failed나 expired를 확인하세요. 그 한 단계가 추가 비용과 많은 혼란을 막아줄 수 있습니다.

코드를 건드리기 전에 제공자 상태 페이지를 확인하세요. 서비스가 저하된 상태라면 로컬 디버깅으로는 많은 것을 알 수 없습니다. 그다음 x-deny-reason 응답 헤더를 검사하세요. 이 확인을 건너뛰면 프록시 수준의 거부가 모델 오류처럼 보일 수 있습니다 ^[3].

또한 latest 대신 kling-v3.0-std 같은 정확한 모델 버전 문자열을 고정하세요. 조용한 모델 업데이트는 어제까지 잘 작동하던 파이프라인에 새로운 검증 실패를 유발할 수 있습니다 ^[3].

더 안정적인 통합을 위한 핵심 요점

대부분의 text-to-video API 실패는 몇 가지 반복 가능한 패턴을 따릅니다. 4xx 오류가 발생하면 요청, 자격 증명, 또는 설정을 바꿔야 합니다. 같은 호출을 다시 보내는 것으로는 보통 아무것도 해결되지 않습니다.

요청 입력 로깅: 모델 ID, 프롬프트 해시, 파라미터 (로깅 모범 사례는 AI API 튜토리얼 참조).
작업 ID, 최종 상태, predict_time, 그리고 전체 오류 메시지 로깅.
중복 렌더링과 두 배 비용을 피하기 위해 작업 상태를 확인한 후 429와 5xx만 재시도 ^[3].
predict_time의 급증을 주시 - 인프라 저하를 조기에 알리는 신호일 수 있습니다 ^[3].

자주 묻는 질문

영상 작업이 실제로 실패했는지 어떻게 알 수 있나요?

작업을 제출할 때 받은 작업 ID로 작업 상태 엔드포인트를 폴링하세요. status 필드가 failed로 돌아오면 작업이 처리되지 않은 것입니다.

다음으로 응답의 error 필드를 보세요. 왜 실패했는지 알려주므로 다음에 무엇을 할지 결정할 수 있습니다:

프롬프트 조정
계정 잔액 확인
인프라 문제라면 대기

작업이 실패 상태로 진입할 때 자동 알림을 받기 위해 웹훅을 사용할 수도 있습니다.

text-to-video API 요청을 언제 재시도해야 하나요?

429 속도 제한과 500 서버 측 문제 같은 일시적 오류는 지수 백오프와 함께 재시도하세요. 그러면 반복 시도를 늦추어 시스템에 부담을 주는 것을 피할 수 있습니다.

504 Gateway Timeout이나 작업 실패의 경우, 다시 시도하기 전에 작업 상태를 확인하세요. 무분별한 재시도는 중복 렌더링을 유발하고 추가 비용을 더할 수 있습니다.

400이나 401 오류는 재시도하지 마세요. 이런 오류는 보통 요청 자체를 먼저 수정해야 한다는 의미입니다.

프롬프트가 제출 후에 차단되는 이유는 무엇인가요?

프롬프트는 보통 제공자의 안전 또는 모더레이션 규칙에 걸려서 차단됩니다. 이는 제출하는 순간에 발생할 수도 있고, 생성 도중 시스템이 금지된 시각적 또는 오디오 콘텐츠를 감지하면 나중에 발생할 수도 있습니다.

그런 일이 발생하면 더 중립적이고 서술적인 언어로 요청을 다시 작성하세요.

이제 직접 테스트해 보세요

모델 마켓에서 원하는 모델을 선택하세요

APIMart 모델 마켓에서 채팅, 이미지, 비디오 모델을 사용해 보고 하나의 통합 API로 모델 기능을 빠르게 경험하세요.

채팅 모델이미지 모델비디오 모델

모델 마켓 보기