에러와 한도

에러 응답

에러는 HTTP 상태 코드와 함께 항상 이 모양으로 와요.

{
  "error": {
    "code": "invalid_request",
    "message": "prompt: Field required",
    "request_id": "177bddb303e0425f807f16b6b8bc4ffc"
  }
}

에러 코드

작업이 실패한 경우는 HTTP 에러가 아니라, 작업 객체의 status: "failed"와 error.code: "generation_failed"로 알려 줘요. → 작업 결과 받기

다시 보내도 되는 에러

한도

한도는 키가 아니라 계정 단위예요. 같은 계정의 키를 여러 개 써도 한도는 하나로 묶여요.

같은 요청을 두 번 보내지 않게

크레딧이 드는 POST 요청에 Idempotency-Key 헤더를 넣으면, 같은 키로 다시 보낸 요청은 새로 처리하지 않고 처음 응답을 그대로 돌려줘요. 다시 만들지도, 다시 차감하지도 않아요.

curl https://api.devdive.ai/v1/videos \
  -H "Authorization: Bearer $DEVDIVE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 6f1c2a8e-order-1042-video" \
  -d '{"prompt": "해 질 녘 바닷가를 달리는 강아지", "duration": 5}'

• 키는 1~255자의 아무 문자열이에요. 요청 하나마다 새 UUID를 만들고, 재시도할 때는 같은 값을 쓰세요.
• 24시간 동안 기억해요. 그 안에 같은 키로 같은 경로·같은 본문을 보내면 처음 응답이 와요. 이때 응답 헤더에 Idempotent-Replayed: true가 붙어요.
• 처음 요청이 아직 처리 중이면, 끝날 때까지 기다렸다가 같은 결과를 돌려줘요.
• 같은 키로 다른 본문을 보내면 422 idempotency_key_reused가 와요.
• 처음 요청이 에러로 끝났으면 기억하지 않아요. 같은 키로 다시 보내면 새로 처리해요.
• 파일 올리기(POST /v1/files)는 이 헤더를 보지 않아요. 크레딧이 들지 않으니 그냥 다시 올리면 돼요.

import os
import uuid

import requests

key = str(uuid.uuid4())  # 이 생성 하나에 쓸 키
for attempt in range(3):
    try:
        res = requests.post(
            "https://api.devdive.ai/v1/images",
            headers={"Authorization": f"Bearer {os.environ['DEVDIVE_API_KEY']}", "Idempotency-Key": key},
            json={"prompt": "눈 덮인 산장과 오로라"},
            timeout=120,
        )
        break
    except (requests.ConnectionError, requests.Timeout):
        continue  # 같은 키로 다시 보내도 두 번 만들지 않아요

타임아웃

• 바로 오는 호출(글, 음성, 분석, 검색)은 모델에 따라 수십 초 걸릴 수 있어요. 클라이언트 타임아웃은 120초 이상으로 두세요.
• GET /v1/jobs/{id}?wait=60을 쓴다면 타임아웃은 90초 정도로 두세요.
• 타임아웃이 나도 서버에서는 처리가 계속될 수 있어요. 생성 요청이라면 Idempotency-Key로 다시 보내거나, 작업이면 같은 작업 ID로 다시 확인하세요.