오류 코드

API는 표준 HTTP 상태 코드를 사용하며 일관된 응답 형식으로 상세한 오류 정보를 반환합니다.

HTTP 상태 코드

코드의미
200성공
400잘못된 요청 -- 유효하지 않은 파라미터
401인증 실패 -- 유효하지 않거나 만료된 토큰
402결제 필요 -- 잔액 부족
403접근 금지 -- 해당 리소스에 대한 접근이 거부됨
404찾을 수 없음 -- 리소스가 존재하지 않음
413페이로드 초과 -- 요청 본문이 너무 큼
429요청 과다 -- 속도 제한 초과
500내부 서버 오류
502잘못된 게이트웨이 -- 업스트림 AI 서비스를 사용할 수 없음
503서비스 사용 불가 -- 일시적 과부하

오류 응답 형식

모든 오류는 일관된 JSON 구조로 반환됩니다:

{
    "error": {
        "code": 400,
        "message": "Invalid prompt parameter",
        "type": "invalid_request_error",
        "param": "prompt",
        "fallback_suggestion": "provide a valid prompt"
    }
}

오류 응답 필드

필드타입설명
error.codeintegerHTTP 상태 오류 코드
error.messagestring사람이 읽을 수 있는 오류 설명
error.typestring오류 유형 카테고리 (아래 참조)
error.paramstring관련 파라미터 이름 (해당되는 경우)
error.fallback_suggestionstring오류 해결을 위한 권장 조치

오류 유형

유형HTTP 코드설명
invalid_request_error400요청 파라미터가 유효하지 않거나 누락됨
authentication_error401유효하지 않거나 만료된 API 토큰
insufficient_quota_error402계정의 크레딧이 부족합니다. 여기에서 충전하세요
permission_error403해당 모델 또는 리소스에 대한 접근 권한이 없음
not_found_error404요청한 리소스(모델, 작업)를 찾을 수 없음
request_too_large_error413요청 본문이 크기 제한을 초과함
rate_limit_error429요청이 너무 많음 -- 권장 간격 후 재시도하세요
internal_server_error500내부 서버 오류 -- 나중에 다시 시도하세요
upstream_error502업스트림 AI 서비스를 사용할 수 없음 -- 다른 모델을 시도하세요
service_unavailable_error503서비스 일시적으로 사용 불가 -- 30초 후 재시도하세요

오류 처리

import requests

response = requests.post(
    "https://api.evolink.ai/v1/videos/generations",
    headers=headers,
    json=payload
)

if response.status_code == 200:
    task = response.json()
    print(f"Task created: {task['id']}")
elif response.status_code == 429:
    # Rate limited — back off and retry
    print("Rate limited. Retrying...")
elif response.status_code == 402:
    print("Insufficient credits. Please top up at https://evolink.ai/dashboard/billing")
else:
    error = response.json().get("error", {})
    print(f"Error [{error.get('type')}]: {error.get('message')}")
    if error.get("fallback_suggestion"):
        print(f"Suggestion: {error.get('fallback_suggestion')}")

실패한 생성

  • 실패한 비디오 생성은 계정에 과금되지 않습니다
  • 비동기 작업을 통해 작업 상태에서 실패 세부 정보를 확인하세요
  • 대부분의 오류는 파라미터를 조정하고 재시도하면 해결할 수 있습니다

관련 문서

얼리 액세스 신청