오류, 멱등성 및 안전한 재시도

논리 작업을 일관되게 유지

유료 생성 엔드포인트에는 8–200자의 Idempotency-Key가 필요합니다. 한 번 생성해 정확한 요청과 저장하고 시간 초과·연결 실패 시 둘 다 재사용하세요.

같은 키와 정규화 본문은 원래 작업을 반환합니다. 같은 키의 다른 본문은 충돌입니다. 접수 중이면 재시도 가능한 진행 중 충돌이 반환될 수 있습니다. 키는 최소 24시간 유지되며 영구 중복 방지를 가정하지 마세요.

범위는 계정, 작업 종류, API 키 식별(MCP는 OAuth 클라이언트)입니다. 다른 API 키로 전환하면 같은 멱등 문자열도 새 작업을 만들 수 있습니다. 불확실한 생성 중 인증 정보를 바꾸기 전에 알려진 작업 ID로 복구하세요.

결과가 불확실하면 원래 작업부터 복구하세요. 몰래 새 키를 만들지 마세요. 의도한 새 생성·변경 요청에는 승인을 받고 새 논리 키를 사용하세요.

오류 응답 읽기

{
  "error": {
    "code": "RATE_LIMITED",
    "message": "Too many requests",
    "param": null,
    "retryable": true,
    "request_id": "example-request-id",
    "details": {}
  }
}

위는 예시이며 동일 메시지 문구를 보장하지 않습니다. HTTP 상태와 error.code로 분기하고 retryable을 확인하며 지원용 request_id를 보관하세요. 원시 헤더, 이미지 본문, 프롬프트, 서명 URL을 로그에 남기지 마세요.

대응 선택

소유권 오류는 의도적으로 찾을 수 없음처럼 보일 수 있습니다. 다른 사용자의 ID를 탐색하지 마세요.

모든 재시도에 한도 설정

Retry-After(초 또는 HTTP 날짜)를 따르고 없으면 지터를 더한 지수 백오프를 사용하세요. 최대 시도 수와 총 기한을 정하세요. 기한은 로컬 대기만 멈추며 접수된 원격 작업은 취소하지 않습니다.

일시적 전송 실패 후 읽기 작업은 재시도할 수 있습니다. 불확실한 유료 생성은 저장된 멱등 키·변경 없는 본문으로만 재시도하세요. 키 없는 업로드나 비멱등 작업을 무작정 반복하지 마세요.

기한에 도달하면 작업 ID를 저장하고 나중에 계속하세요. 종료 실패는 새 내보내기·생성 선택 전에 부분 출력을 확인하세요.

계정 한도 및 진단

PROVIDER_CONTENT_REJECTED는 현재 확인된 Seedance 콘텐츠 심사 거부이며 동일 요청을 반복할 일시적 오류가 아닙니다. 작업의 credits.status, credits.refunded, credits.released를 읽으세요. credits.charged는 이미 순차감액이므로 반환분을 다시 빼지 마세요. 출력·내보내기 전 확인된 거부는 원클릭 전체 금액을 반환합니다. 로컬 시간 초과·내보내기 실패는 같은 조건이 아니며 반환도 새 유료 작업 승인이 아닙니다.

현재 한도는 GET /account에서 확인하세요. 응답 제한 헤더는 현재 버킷을 설명할 수 있습니다. 키를 늘려도 계정 용량은 늘지 않습니다. 모든 클라이언트가 한 번에 조회하지 않도록 분산하세요.

지원팀에는 공개 요청 ID, 알려진 작업 ID, 시간, 코드, 짧은 설명을 보내고 비밀·비공개 입력은 가리세요. 미완료 결과는 상태 조회 및 다운로드, 제한된 재시도는 Python 예제를 참고하세요.