에러 해결

요청이 잘못되거나 처리에 실패하면, 서버는 **에러(오류)**를 JSON 형태로 돌려줍니다. 당황하지 마세요 — 대부분은 원인이 명확하고 금방 고칠 수 있어요.

모든 에러에는 **code(에러 코드)**가 들어 있습니다. 이 코드만 보면 "무엇이 문제인지"를 바로 알 수 있어요.

에러는 이렇게 생겼어요

{
  "error": {
    "code": "invalid_api_key",
    "message": "사람이 읽을 수 있는 설명 메시지",
    "type": "modoo_error"
  }
}

• code — 문제의 종류(아래 표에서 찾아보세요).
• message — 무엇이 잘못됐는지 알려주는 설명.
• type — 항상 modoo_error 입니다(이 API가 낸 에러라는 표시).

가장 먼저 볼 곳

문제가 생기면 code 부터 확인하세요. 아래 표와 설명에서 같은 코드를 찾아 그대로 따라 하면 됩니다.

---

한눈에 보는 에러 표

code	HTTP	뜻	해결
missing_api_key	401	키 헤더가 없음	Authorization 헤더를 넣으세요
invalid_api_key	401	키가 틀리거나 비활성	대시보드에서 키를 확인/재발급
insufficient_credits	402	크레딧 소진	크레딧을 충전(구독 확인)
model_not_found	404	모델 이름 오타	GET /v1/models로 정확한 이름 확인
not_found	404	없는 작업/런 id	job_id/run_id 확인
no_backend_account	409	계정에 AI 사용 설정이 아직 연결 안 됨	구독/설정을 확인(고객센터 문의)
invalid_request	422	요청 형식 오류	messages 또는 prompt를 넣었는지 확인
invalid_workflow	400	블럭 연결이 호환되지 않음	에러 메시지의 안내대로 연결 수정
rate_limited	429	호출이 너무 많음	잠시 후 재시도
daily_quota_exceeded	429	하루 사용 한도 도달	내일 다시 시도하거나 한도 상향
upstream_error	502	일시적 처리 오류	잠시 후 재시도

---

인증·크레딧 문제 (401 / 402)

"내가 누구인지" 확인하는 열쇠(API 키)나, 사용에 필요한 크레딧과 관련된 문제입니다.

missing_api_key

무슨 뜻인가요? 요청에 API 키(신분증 역할)를 아예 넣지 않았다는 뜻이에요.

왜 생기나요? 요청을 보낼 때 Authorization 헤더를 빠뜨린 경우입니다.

어떻게 해결하나요?

1. 모든 요청에 아래 헤더를 넣습니다.

Authorization: Bearer sk-modoo-...

2. sk-modoo-... 자리에는 대시보드에서 발급받은 실제 키를 넣으세요.

{ "error": { "code": "missing_api_key", "message": "Authorization 헤더가 없습니다.", "type": "modoo_error" } }

invalid_api_key

무슨 뜻인가요? 키를 넣긴 했는데, 그 키가 틀렸거나 더 이상 쓸 수 없는(비활성) 키라는 뜻이에요.

왜 생기나요? 키를 복사할 때 일부가 빠졌거나, 오래돼 사용 중지된 키를 쓴 경우가 많아요.

어떻게 해결하나요?

1. 대시보드에서 키를 다시 복사해 정확히 붙여 넣으세요(앞뒤 공백 주의).
2. 그래도 안 되면 대시보드에서 키를 재발급한 뒤 새 키를 사용하세요.

{ "error": { "code": "invalid_api_key", "message": "키가 올바르지 않거나 비활성 상태입니다.", "type": "modoo_error" } }

insufficient_credits

무슨 뜻인가요? 남은 크레딧이 부족해서 이번 요청을 처리할 수 없다는 뜻이에요. 크레딧은 AI를 쓸 때마다 조금씩 차감됩니다.

왜 생기나요? 사용량이 많아 크레딧을 다 썼거나, 구독이 만료된 경우입니다.

어떻게 해결하나요?

1. GET /v1/credits 로 남은 크레딧을 확인하세요.

curl https://modoo.devdive.me/v1/credits \
 -H "Authorization: Bearer sk-modoo-..."

2. 크레딧이 0에 가깝다면 대시보드에서 충전하거나 구독 상태를 확인하세요.

{ "error": { "code": "insufficient_credits", "message": "크레딧이 부족합니다.", "type": "modoo_error" } }

크레딧이 자꾸 부족하다면

저렴한 모델(modoo-text-mini, modoo-text-nano)로 바꾸면 크레딧을 아낄 수 있어요. 모델 선택은 모델 안내를 참고하세요.

---

요청 문제 (400 / 404 / 422)

요청 자체에 오타나 형식 문제가 있을 때 나옵니다. 보낸 내용을 살짝만 고치면 됩니다.

model_not_found

무슨 뜻인가요? 요청한 모델 이름을 찾을 수 없다는 뜻이에요. 대부분 오타입니다.

왜 생기나요? modoo-text-pro 를 modoo-textpro 처럼 잘못 적거나, 존재하지 않는 이름을 쓴 경우예요.

어떻게 해결하나요?

1. GET /v1/models 로 정확한 모델 이름을 확인하세요.

curl https://modoo.devdive.me/v1/models \
 -H "Authorization: Bearer sk-modoo-..."

2. 응답의 id 값을 그대로 복사해 model 에 넣으세요.

{ "error": { "code": "model_not_found", "message": "해당 모델을 찾을 수 없습니다.", "type": "modoo_error" } }

not_found

무슨 뜻인가요? 조회하려는 작업(job_id)이나 워크플로우 실행(run_id)이 존재하지 않는다는 뜻이에요.

왜 생기나요? 번호에 오타가 있거나, 다른 사람의(내 것이 아닌) 작업 번호를 조회한 경우입니다.

어떻게 해결하나요?

1. 작업을 요청했을 때 받은 job_id / run_id 를 정확히 복사했는지 확인하세요.
2. 조회 주소가 GET /v1/jobs/{job_id} 형식과 맞는지 확인하세요(폴링 방법은 API 레퍼런스 참고).

{ "error": { "code": "not_found", "message": "해당 작업을 찾을 수 없습니다.", "type": "modoo_error" } }

invalid_request

무슨 뜻인가요? 요청의 형식이 잘못됐다는 뜻이에요. 꼭 필요한 값이 빠졌을 가능성이 큽니다.

왜 생기나요? 텍스트 요청에서 messages 도 prompt 도 넣지 않았거나, 필수 항목을 빠뜨린 경우입니다.

어떻게 해결하나요?

1. 텍스트 요청이라면 messages 또는 prompt 둘 중 하나는 반드시 넣으세요.
2. 예시대로 항목 이름과 형식이 맞는지 다시 확인하세요(모델 예시 참고).

{ "error": { "code": "invalid_request", "message": "messages 또는 prompt가 필요합니다.", "type": "modoo_error" } }

invalid_workflow

무슨 뜻인가요? 여러 AI 작업을 이어 붙인 워크플로우의 연결이 서로 맞지 않는다는 뜻이에요.

왜 생기나요? 아직 실행되지 않은(뒤에 있는) 블럭을 참조하거나, 존재하지 않는 출력 항목을 가져오려 하거나, 종류가 맞지 않는 결과를 다음 블럭 입력으로 연결한 경우입니다.

어떻게 해결하나요?

1. 에러 message 에 어떤 연결이 문제인지 친절히 안내되어 있으니 그대로 고치세요.
2. 앞 블럭의 결과만 뒤 블럭에서 참조하도록 순서를 맞추세요.
3. 자세한 연결 규칙은 워크플로우 안내를 참고하세요.

{ "error": { "code": "invalid_workflow", "message": "뒤에 있는 블럭 'draft'를 참조할 수 없습니다.", "type": "modoo_error" } }

워크플로우는 실행 전에 미리 검사돼요

연결이 맞지 않으면 실제 실행 전에 이 에러로 미리 알려드립니다. 덕분에 크레딧을 낭비하지 않아요.

no_backend_account

무슨 뜻인가요? 계정에 AI 사용 설정이 아직 연결되지 않았다는 뜻이에요. (HTTP 409)

왜 생기나요? 구독은 되어 있지만 AI 사용을 위한 초기 설정이 아직 완료되지 않은 경우입니다.

어떻게 해결하나요?

1. 대시보드에서 구독 및 사용 설정이 정상인지 확인하세요.
2. 설정이 정상인데도 계속 나온다면 고객센터에 문의하세요.

{ "error": { "code": "no_backend_account", "message": "AI 사용 설정이 아직 연결되지 않았습니다.", "type": "modoo_error" } }

---

한도 문제 (429)

한꺼번에 너무 많이 쓰면 서비스 안정을 위해 잠깐 제한이 걸립니다. 문제가 아니라 정상적인 보호 장치예요.

rate_limited

무슨 뜻인가요? 짧은 시간에 요청을 너무 많이 보냈다는 뜻이에요.

왜 생기나요? 분당 허용된 호출 수(레이트리밋)를 넘긴 경우입니다.

어떻게 해결하나요?

1. 잠깐(몇 초~1분) 기다렸다가 다시 시도하세요.
2. 반복 요청이 많다면, 요청 사이에 약간의 간격을 두세요.
3. 모델별 한도는 모델 안내의 호출 한도 표를 참고하세요.

{ "error": { "code": "rate_limited", "message": "요청이 너무 많습니다. 잠시 후 다시 시도하세요.", "type": "modoo_error" } }

daily_quota_exceeded

무슨 뜻인가요? 하루 동안 쓸 수 있는 사용 한도에 도달했다는 뜻이에요.

왜 생기나요? 그날 정해진 사용 한도를 모두 소진한 경우입니다.

어떻게 해결하나요?

1. 다음 날 한도가 초기화되면 다시 사용할 수 있습니다.
2. 더 많이 써야 한다면 대시보드나 고객센터를 통해 한도 상향을 요청하세요.

{ "error": { "code": "daily_quota_exceeded", "message": "하루 사용 한도에 도달했습니다.", "type": "modoo_error" } }

---

⏳ 일시적인 오류 (502)

내 요청은 문제가 없는데 처리 과정에서 잠깐 문제가 생긴 경우입니다. 대부분 다시 시도하면 해결돼요.

upstream_error

무슨 뜻인가요? AI 처리 중 일시적인 오류가 발생했다는 뜻이에요.

왜 생기나요? 순간적인 부하나 일시적 장애 등, 대개 잠깐 지나가는 문제입니다.

어떻게 해결하나요?

1. 잠시 후 같은 요청을 다시 보내세요. 보통 한두 번 재시도하면 성공합니다.
2. 계속 반복된다면 시간을 조금 더 두었다가 시도하거나 고객센터에 문의하세요.

{ "error": { "code": "upstream_error", "message": "일시적인 처리 오류가 발생했습니다. 잠시 후 다시 시도하세요.", "type": "modoo_error" } }

재시도할 때 팁

같은 요청을 반복할 때는 조금씩 간격을 늘려가며(예: 1초 → 3초 → 10초) 시도하면 성공 확률이 높아집니다.

---

그래도 해결이 안 되면

• 먼저 빠른 시작으로 기본 설정(키, 헤더)을 다시 점검해 보세요.
• 정확한 요청 형식은 API 레퍼런스에서 확인할 수 있어요.
• 그래도 같은 에러가 반복된다면, 에러의 code 와 message 를 함께 적어 고객센터에 문의하세요. 원인을 훨씬 빠르게 찾을 수 있습니다.