오류
모든 Direct API 오류 코드의 의미와 재시도 여부, 그리고 유료 호출이 5xx로 실패했을 때 해야 할 일을 알아봅니다.
모든 오류는 같은 본문을 가집니다. HTTP 상태와 code로 분기하고, 사람에게는 description이나 error.message를 보여 주세요.
{
"description": "Human-readable explanation, safe to log.",
"code": "machine_readable_code",
"data": { "request_id": "…", "…": "…" },
"error": { "error_code": "…", "message": "…" }
}성공이든 오류든 모든 응답에는 X-Request-Id가 포함됩니다. 지원팀에 문의할 때 이 값을 함께 알려 주세요.
오류 코드
| HTTP | code | 의미 | 재시도 |
|---|---|---|---|
| 400 | invalid_request | 잘못된 JSON, 알 수 없는 본문 필드, 또는 input이 도구의 스키마를 통과하지 못함(잘못된 필드마다 이름이 표시됨) | 아니요, 요청을 수정 |
| 401 | invalid_api_key | 키가 없거나, 형식이 잘못되었거나, 폐기되었거나, 만료됨 | 아니요 |
| 402 | insufficient_credits | 조직이 호출 비용을 지불할 수 없음 | 충전 후 |
| 402 | api_key_credit_limit_reached | 호출이 키의 일일, 월간 또는 총 한도를 넘게 됨(data.period에 어느 한도인지 표시) | 기간이 초기화되거나 한도가 늘어난 후 |
| 402 | subscription_paused | 조직의 구독이 일시 중지됨 | 구독이 재개된 후 |
| 402 | payment_required | 조직의 구독 결제가 연체됨 | 결제가 완료된 후 |
| 403 | direct_api_disabled | 이 조직에 Direct API가 활성화되지 않음 | 아니요, Morphic에 문의 |
| 403 | insufficient_scope | 키에 이 도구가 필요로 하는 범위가 없음(data.required_scopes) | 아니요, 다른 키 사용 |
| 403 | plan_upgrade_required | 모델이나 기능이 플랜에 포함되어 있지 않음 | 아니요 |
| 403 | tool_not_available | 크레딧을 청구하는 도구인데 조직에 유료 도구가 아직 활성화되지 않음(data.tool에 도구 이름 표시). Morphic 담당자가 활성화함 | 아니요 |
| 403 | model_disabled_by_organization | 조직 관리자가 이 모델, 해상도 또는 오디오 옵션을 끄고 API에 허용하지 않음 | 아니요, 관리자에게 문의 |
| 404 | not_found | 알 수 없는 도구, 생성 작업 또는 웹훅이거나, 이 키가 접근할 수 없는 대상 | 아니요 |
| 409 | idempotency_conflict | Idempotency-Key를 다른 본문이나 도구에 재사용함 | 아니요, 새 키 사용 |
| 409 | idempotency_in_progress | 이 키를 사용한 원래 요청이 아직 실행 중 | 예, 1초 후 |
| 409 | idempotency_outcome_unknown | 이 Idempotency-Key를 사용한 원래 요청이 실패했거나 실행되었을 수 있는 시점 이후 응답하지 않아 결과를 알 수 없음 | 아니요: 결과를 확인한 다음 새 키 사용 |
| 413 | payload_too_large | 본문이 1 MB를 넘음 | 아니요 |
| 422 | tool_refused | 입력 형식은 올바르지만 실행할 수 없음. 청구 없음 | 아니요, 입력을 변경 |
| 429 | rate_limited | 속도 한도에 도달함 | 예, Retry-After 후 |
| 500 | internal_error | Morphic 측 오류 | 무료 호출은 예, 유료 호출은 아래 참조 |
| 503 | service_unavailable | 일시적인 과부하 또는 유지보수 | 무료 호출은 백오프와 함께 예, 유료 호출은 아래 참조 |
| 504 | tool_timed_out | 도구가 60초 안에 응답하지 않음. 생성 작업을 시작하는 호출은 이미 작업을 시작했을 수 있음 | 무료 호출은 예, 유료 호출은 아래 참조 |
422 tool_refused는 해당 필드, 값, 그리고 사용할 수 있었던 값을 표시합니다. 도구 거부를 참조하세요. 시작된 후 실패한 생성 작업은 생성 작업 객체에 자체 error.error_code를 표시하며, 청구 금액은 환불됩니다.
5xx로 응답한 유료 호출
500, 503 또는 504로 응답한 유료 호출은 실패하기 전에 작업을 시작하고 비용을 청구했을 수 있습니다. 같은 Idempotency-Key로 재시도해도 두 번 실행되지 않으며, 재시도는 409 idempotency_outcome_unknown으로 응답합니다.
- 호출이 무엇을 했는지 확인합니다:
list_generations, 또는 시간으로 필터링한GET /v1/direct/usage. - 시작되지 않은 작업에 대해서만 새
Idempotency-Key를 보냅니다.
응답이 전혀 도착하지 않은 경우(연결 끊김)에는 같은 키로 재시도하세요. 저장된 응답을 받거나, 아직 실행 중이면 409 idempotency_in_progress를 받습니다. 멱등성을 참조하세요.
문제가 있거나 궁금한 점이 있으면 언제든지 연락해 주세요. 기꺼이 도와드리겠습니다. 다음 주소로 이메일을 보내 주세요: support@morphic.com.