문제 해결과 복구

아래 절마다 눈에 보이는 증상에서 출발해 흔한 원인을 설명하고, 무엇을 하면 되는지 알려 드립니다. 오류 번호 하나하나의 정확한 의미는 오류에 있고, 이 페이지는 "그래서 이제 뭘 하면 되지?"에 답하는 짝이 되는 페이지입니다.

내 문제 찾기

쓸모 있는 증거 남기기

무엇이든 바꾸기 전에 무슨 일이 있었는지 먼저 적어 두세요. 아래의 모든 단계가 빨라지고, 지원팀에 문의할 때 필요한 것도 바로 이 정보입니다.

• 시각. 가능하면 UTC로 적습니다.
• 호출한 엔드포인트. 예: POST /api/v1/jobs/createTask.
• 응답의 HTTP 상태와 본문에 들어 있는 code 값.
• request_id: 응답 본문과 X-Request-Id 응답 헤더에 들어 있습니다.
• 받았다면 작업 ID. job_으로 시작하며, 콘솔의 로그 페이지에도 나옵니다.

다음 세 가지 상황은 대처 방법이 다르므로 꼭 구분하세요. 첫째, API가 요청을 명시적으로 거부한 경우입니다. JSON 오류를 받았고, 아무것도 만들어지지 않았으며 과금되지도 않았습니다. 둘째, 응답을 전혀 받지 못한 경우입니다. 시간 초과나 연결 끊김으로, 작업이 만들어졌을 수도 있습니다(아래 참고). 셋째, 작업이 접수된 뒤 나중에 실패한 경우입니다. state: "failed"인 작업 ID가 있습니다.

응답이 JSON이 아니라면(예를 들어 HTML 페이지나 일반 텍스트), API에 닿기 전에 저희 엣지 네트워크에서 돌아온 응답입니다. HTTP 상태와 본문의 첫 몇 줄을 적어 두세요. 이런 형태의 403 페이지는 대개 저희가 서비스할 수 없는 지역에서 보낸 요청이라는 뜻이며, 다시 시도해도 달라지지 않습니다.

API 키, 비밀번호, 프롬프트 전문, 원본 파일은 일반 로그나 지원 요청에 절대 넣지 마세요.

결제했는데 잔액이 바뀌지 않음

• 카드: 결제 대행사의 확인이 저희에게 도착해야 잔액이 바뀌며, 보통 몇 초면 됩니다. 결제를 새로 고치고 충전 주문을 확인하세요.
• 암호화폐: 네트워크가 거래를 확인한 뒤 잔액에 반영되며, 보통 몇 분 걸립니다. 표시된 금액보다 적게 보냈거나 결제 페이지가 만료된 뒤에 보낸 결제는 자동으로 반영되지 않습니다.
• 수동 송금: 충전 주문에서 주문을 열고 은행 참조 번호나 거래 해시를 제출하세요. 저희가 직접 확인하며, 보통 몇 시간 안에 끝납니다.

모든 경우는 계정 설정 → 자주 겪는 문제에 정리되어 있습니다. 그래도 반영되지 않았나요? 지원에서 문의 유형을 결제와 충전으로 골라 대화를 시작하고, 주문 ID와 함께 암호화폐라면 거래 해시도 적어 주세요. 카드 번호나 비밀번호는 절대 보내지 마세요.

모든 호출이 401이나 403을 반환함

비용이 들지 않고 아무것도 바꾸지 않는 호출, 즉 잔액 조회부터 해 보세요.

echo "${SPICY_API_KEY:0:9}"
curl https://api.spicyapi.ai/api/v1/chat/credit \
  -H "Authorization: Bearer $SPICY_API_KEY"

첫 줄에는 sk-spicy-가 출력되어야 합니다. 아무것도 출력되지 않으면 이 터미널에 키가 설정되지 않은 것이니 다시 설정하세요(계정 설정 참고). 그런 다음 응답의 msg를 읽으세요.

이 중 어느 것도 다시 시도한다고 나아지지 않습니다.

잔액, 한도, 지원 문의

• 40201: 사용 가능 잔액으로 작업의 예상 가격을 감당할 수 없습니다. 잔액을 충전한 뒤(계정 설정 참고) 같은 요청을 같은 Idempotency-Key로 다시 보내세요. 프로모션 지원금은 대상 모델에만 쓸 수 있습니다.
• 40202: 지출 한도에 닿았습니다. 어느 한도인지는 msg에 나옵니다. 키 한도(This key has reached its …)는 API 키 → 편집에서 올리거나, 저절로 초기화되기를 기다리면 됩니다(일 한도는 UTC 00:00, 월 한도는 매월 1일에 초기화되고 누적 한도는 초기화되지 않습니다). 팀 한도(Workspace … budget has been reached)는 소유자, 관리자, 예산 관리자가 팀 페이지에서 올립니다. 플랫폼 한도(Platform quota for today is exhausted…)는 올릴 수 없으니 UTC 00:00 이후에 다시 시도하세요. 지출 한도 전체는 과금을 보세요.
• 429: 요청이 너무 많습니다. Retry-After에 적힌 초만큼 기다린 뒤 속도를 늦추세요. 촘촘한 반복 폴링 대신 웹훅을 쓰는 것이 가장 효과적입니다. 메시지가 Too many pending uploads…라면 기다려도 소용없으니, 이미 시작한 업로드를 먼저 끝내세요. 레이트 제한을 보세요.

지원팀에 문의할 때: 콘솔의 지원에서 대화를 시작하거나 support@spicyapi.ai로 이메일을 보내세요. 위에서 모은 증거를 함께 적어 주세요. 시각, 엔드포인트, code, request_id나 작업 ID, 기대한 결과와 실제로 일어난 일, 그리고 비공개 값을 지운 요청의 구조입니다. API 키는 절대 보내지 마세요.

모델이 없거나 사용할 수 없음

• 모델이 내 목록에 없거나 404가 나올 때: API 키를 붙여 GET /api/v1/models를 호출하고, enabled와 available이 모두 true인 모델을 골라 그 ID를 정확히 그대로 복사해 쓰세요. 웹사이트에 모델 페이지가 있다고 해서 내 키로 지금 그 모델을 호출할 수 있다는 뜻은 아닙니다. 모델 카탈로그와 스키마를 보세요.
• 50301: 지금은 그 모델이 작업을 받을 수 없습니다. 간격을 점점 늘려 가며 몇 번 다시 시도한 뒤 멈추세요. 요청을 반복한다고 사용할 수 없는 모델이 열리지는 않습니다. 카탈로그를 새로 조회하고, 다른 모델로 바꾸기 전에는 비용을 내는 사람에게 먼저 물어보세요.
• 40004: 모델은 작동하지만 이 설정 조합으로는 쓸 수 없습니다. msg의 괄호 안에 문제가 된 설정 이름이 나옵니다. 다시 시도하지 말고 그 값(예: 해상도나 화면 비율)을 바꾸세요.
• 40301: 모델은 있지만 이 키로는 쓸 수 없습니다. 키의 허용할 모델을 편집하세요.

잘못된 입력 또는 견적 충돌

• 400: 내 input을 카탈로그에 있는 그 모델의 현재 inputSchema와 비교하세요. 필드 이름, 타입, 허용되는 값, 조건부 필수 항목을 확인합니다. 모델이 나열하지 않은 필드는 빼세요. 모델마다 스키마가 따로 있으므로, 모델을 바꾼 뒤에는 다시 확인하세요.
• 40003: 업로드한 파일이 업로드 URL을 요청할 때 선언한 내용과 맞지 않습니다. 올바른 contentType과 크기로 업로드 URL을 새로 요청하고 다시 업로드하세요.
• 413: 요청 본문이 너무 큽니다. 미디어를 요청에 직접 넣지 말고 미디어 업로드 절차로 올리세요.
• 40901: 견적이 만료됐거나, 견적을 받은 뒤 요청이 바뀌었거나, 가격이 바뀌었습니다. 새 견적을 받아 비용을 내는 사람에게 새 금액을 보여 주고 다시 확인을 받으세요. 견적과 호환성을 보세요.
• 그 밖의 409: 어떤 작업이었는지에 따라 처리합니다. 이미 다른 요청 내용에 쓰인 멱등 키라면 끝없이 재시도할 것이 아니라, 새 요청에 알맞은 새 Idempotency-Key를 붙여야 합니다. 409를 다시 시도해도 되는 경우는 오류를 보세요.

작업 ID 없이 제출이 시간 초과됨

시간 초과만으로는 작업이 만들어졌는지 알 수 없습니다. 새 멱등 키를 붙여 그냥 다시 보내지는 마세요. 두 번째 작업이 만들어져 두 번 과금될 수 있습니다.

클라이언트의 시간 초과, 닫아 버린 브라우저 탭, 끊긴 스트림은 접수된 작업을 취소하지 않으며, 접수된 작업은 취소할 수 없습니다.

작업이 실패함

실패하거나 만료된 작업은 보통 예약 금액이 전액 해제됩니다. 다만 모델 페이지에 명시된 일부 콘텐츠 거부는 접수 시 견적 금액으로 과금됩니다. 최종 청구액은 settled와 cost로 확인하세요.

• 그대로 다시 시도하지 마세요: invalid_request, unsupported_combination, content_rejected(선택한 모델이 콘텐츠를 거절했습니다. 프롬프트나 모델을 바꾸세요).
• 잠시 뒤 다시 시도할 만합니다: rate_limited, upstream_unavailable, upstream_failed.
• 먼저 고치세요: invalid_asset(파일을 다시 업로드하세요), timeout(길이를 줄이거나 해상도를 낮춰 보세요), generation_failed(같은 입력은 대개 같은 방식으로 다시 실패합니다).

errorMessage는 사람이 읽도록 이유를 설명하며, 모델이 영어로 보낸 이유가 그대로 담겨 있을 수도 있습니다. 코드에서는 errorCode로만 분기하세요. 작업 실패 코드의 전체 표는 오류에 있습니다. 재시도는 새 작업이므로, 성공하면 다시 과금됩니다.

작업이 queued나 running에 머묾

생성에는 시간이 걸립니다. 긴 영상은 몇 분씩 걸리기도 합니다. 모든 작업에는 서버 쪽 마감 시각이 있으며, recordInfo에 deadlineAt으로 들어 있습니다.

• deadlineAt 전: 콜백을 계속 기다리거나, 간격을 점점 늘리면서 recordInfo를 폴링하세요(1초마다 조회하지는 마세요).
• 마감 시각이 지난 뒤: 작업은 errorCode: "timeout"과 함께 expired로 저절로 끝나고, 예약된 금액은 전액 돌아옵니다. 따로 취소할 것은 없으며, 접수된 작업은 어차피 취소할 수 없습니다.

deadlineAt을 한참 넘겼는데도 작업이 running에 머문다면 작업 ID와 함께 지원팀에 문의하세요.

업로드는 성공했지만 입력이 거부됨

• 확정 단계를 건너뛰었습니다. 파일 PUT이 성공한 것만으로는 부족합니다. files/{fileId}/commit을 호출한 다음, 돌려받은 spicy:// URI를 모델의 입력 필드에 넣으세요. uploadUrl 자체를 넣으면 안 됩니다.
• 파일이 티켓과 맞지 않습니다. 선언한 Content-Type, 크기, 형식을 확인하세요. 맞지 않으면 40003이 반환됩니다.
• 만료되었습니다. 업로드한 파일은 확정 응답의 expiresAt까지 쓸 수 있습니다. 기본값은 1일이며, 작업이 끝나면 업로드를 삭제하도록 계정이 설정되어 있다면 그보다 일찍 만료됩니다. 그래서 작업을 재시도할 때 파일을 새로 업로드해야 할 수도 있습니다.
• 다른 계정의 파일입니다. spicy:// URI는 그 파일을 업로드한 계정의 키로만 쓸 수 있습니다.

전체 업로드 절차는 미디어를 보세요.

콜백이 오지 않거나 다운로드가 만료됨

콜백이 오지 않았다면:

1. callBackUrl이 인터넷에서 접근할 수 있는 https:// 주소인지 확인하세요. 일반 http:// 주소는 받지 않습니다.
2. 수신 측이 JSON을 파싱하기 전에 원래 요청의 바이트 그대로 서명을 검증하는지, 그리고 2xx로 빠르게 응답하는지 확인하세요. 오래 걸리는 처리는 자체 대기열로 넘기세요. 최근에 서명 키를 교체했다면 수신 측은 새 키를 써야 합니다. 두 키를 함께 쓸 수 있는 유예 기간은 없습니다. 웹훅을 보세요.
3. 콘솔의 웹훅에서 전송 기록을 확인하세요. 그곳에서 전송을 다시 보낼 수도 있습니다.
4. 그동안에는 recordInfo로 작업을 조회하세요. 폴링은 언제든 쓸 수 있는 대안입니다. 웹훅을 보세요.

콜백은 두 번 이상 오거나 늦게 올 수 있으니, 주문을 처리하기 전에 중복을 걸러 내세요.

다운로드 링크나 파일이 사라졌다면:

• 다운로드 링크는 20분 동안 유효합니다. 결과가 아직 보관 중이라면 새 링크를 요청하면 됩니다. 예전 링크를 새로 고쳐서는 되지 않습니다.
• 결과를 아직 저장소로 복사하는 중이라면 몇 초 기다렸다가 다시 요청하세요.
• 결과는 최대 약 14일 동안 보관되며, 계정에서 더 짧은 보관 기간을 설정했다면 그보다 짧습니다. contentState가 expired나 purged가 되면 파일을 되살릴 수 없으니 모델을 다시 실행하세요. 보관과 파기를 보세요.

스트림이 일찍 끝남

스트림을 프로토콜에 맞게 파싱하기 전에 HTTP 상태와 Content-Type부터 확인하세요. 네트워크로 들어오는 조각 하나하나가 완전한 이벤트는 아니며, 연결이 닫혔다고 성공한 것도 아닙니다. 그 프로토콜의 마지막 이벤트, 오류 이벤트, 그리고 내 애플리케이션이 정한 마감 시간을 확인하세요. 끊긴 스트림은 무료였다거나 비용 없이 다시 보낼 수 있다고 가정하지 마세요. 연결이 끊기기 전에 기록된 유효한 사용량은 과금될 수 있습니다. request_id를 보관해 두고 사용 기록을 확인하세요. 텍스트와 스트리밍을 보세요.

팀 권한

• 키를 만들 수 없습니다. 콘솔 왼쪽 사이드바 맨 위의 범위 선택기가, 내 역할이 예산 관리자나 읽기 전용인 팀으로 설정되어 있는 경우입니다. 키를 만들려면 소유자, 관리자, 개발자 중 하나의 역할이 필요합니다. 개인 범위로 바꾸거나, 팀 관리자에게 개발자 역할을 요청하세요.
• 작업은 보이는데 프롬프트나 결과가 보이지 않습니다. 예산 관리자와 읽기 전용 멤버는 상태, 비용, 사용량만 볼 수 있습니다.
• 초대를 수락할 수 없습니다. 초대를 받은 바로 그 이메일 주소로 로그인하세요. 초대는 7일 뒤 만료되니, 만료됐다면 새 초대를 요청하세요.
• 팀 키가 40201로 멈췄습니다. 팀 키는 팀 소유자의 잔액을 쓰므로, 소유자가 잔액을 충전해야 합니다.

역할과 팀 한도는 콘솔과 팀을 보세요.

인보이스를 발행할 수 없음

• 인보이스 정보가 다 채워지지 않았습니다. 인보이스에는 이름(회사명 또는 본인 이름), 주소 1행, 도시, 국가가 필요하며, 결제 → 인보이스 맨 위에서 한 번만 입력하면 됩니다.
• 인쇄할 수 없는 문자가 있습니다. 인보이스에는 라틴, 그리스, 키릴 문자만 쓸 수 있습니다. 일본어나 한국어 회사명은 등록된 로마자 표기로 적으세요.
• 이미 발행된 인보이스가 있습니다. 결제를 마친 충전 건과 마감된 달은 각각 한 번만 인보이스를 발행할 수 있으니, 기존 문서를 내려받으세요. 정보를 고치려면 그 인보이스에서 다시 발행을 누르세요.
• 그 달을 고를 수 없습니다. 사용 내역서는 이미 끝났고 실제로 지출이 있었던 달에만 발행할 수 있습니다.

인보이스와 사용 내역서는 과금을 보세요.

관련 안내

오류 · 프로덕션 연동 · 멱등성 · 미디어 · 웹훅 · 텍스트와 스트리밍 · 계정 설정