오류 코드 레퍼런스

일반적인 HTTP 상태, 비동기 작업 오류 코드 및 플랫폼 프로그램 오류 코드를 확인합니다.

오류 응답에는 일반적으로 HTTP 상태와 본문의 프로그램 오류 코드가 함께 포함됩니다. 먼저 HTTP 상태를 판단한 후 실제 반환된 type, code 및 message를 읽어야 합니다. 프로토콜이나 상위 서비스에 따라 반환 필드가 다를 수 있습니다.

현상별 문제 해결은 오류 및 문제 해결을 먼저 참고합니다. 이 페이지는 오류의 의미를 확인하는 용도이며 개별 Endpoint의 응답 설명을 대체하지 않습니다.

HTTP 상태

HTTP 상태	일반적인 의미	일반적인 원인	권장 처리
`400`	유효하지 않은 요청	JSON, 필수 필드, 매개변수 타입, 파일 형식 또는 입력 내용 불일치	오류 정보에 따라 요청을 수정하며 그대로 재시도하지 않습니다
`401`	인증 실패	API 키 누락, 무효 또는 프로토콜 요구 사항과 다른 인증 Header	Bearer 또는 프로토콜 전용 Header를 확인하고 무효 키를 교체합니다
`403`	권한 또는 할당량 부족	계정, 키, 모델 권한, IP 범위 또는 가용 할당량이 요청을 충족하지 못함	계정과 키의 제한 및 대상 모델의 사용 가능 여부를 확인합니다
`404`	리소스 없음	Endpoint, 모델 ID, 작업 ID 또는 Video ID 없음	최종 URL, 리소스 ID 및 소유 계정을 확인합니다
`429`	요청 제한	요청 빈도, 동시 요청, 할당량 또는 서비스 용량 한도 도달	부하를 줄이고 제한적으로 재시도하며 계속 실패하면 Request ID를 보관합니다
`500`	요청 처리 실패	요청 변환, Token 계산, 가격 정보 또는 플랫폼 처리 오류	마스킹된 오류 정보와 Request ID를 보관하고 나중에 제한적으로 재시도합니다
`502`	상위 게이트웨이 오류	상위 서비스의 유효하지 않은 응답 또는 게이트웨이 전달 실패	제한적으로 재시도하며 계속 실패하면 기술 지원에 문의합니다
`503`	일시적인 서비스 장애	플랫폼 또는 상위 서비스의 과부하, 유지보수 또는 처리 용량 부족	백오프 재시도를 사용하고 잦은 요청을 계속 보내지 않습니다
`504`	요청 시간 초과	상위 서비스의 처리 시간이 게이트웨이 대기 시간을 초과함	Request ID를 기록하고 비동기 작업은 원래 작업 상태부터 조회합니다

HTTP 상태만으로 원인을 확정할 수 없습니다

404는 경로, 모델 또는 작업이 없음을 나타낼 수 있고, 429는 빈도, 동시 요청, 할당량 또는 서비스 용량에서 발생할 수 있습니다. 실제 오류 본문과 Request ID를 함께 확인해야 합니다.

일반적인 오류 응답 구조

OpenAI 호환 API는 일반적으로 error 객체에 오류 정보를 담습니다:

{
  "error": {
    "message": "요청이 실패한 구체적인 이유",
    "type": "invalid_request_error",
    "param": "model",
    "code": "model_not_found"
  }
}

일부 플랫폼 작업 API는 code와 message를 직접 반환합니다:

{
  "code": "task_not_exist",
  "message": "조회한 작업 ID가 없습니다"
}

모든 API의 오류 응답 구조가 완전히 같다고 가정해서는 안 됩니다. 파싱 전에 해당 API 레퍼런스를 확인하고 선택 필드가 누락된 경우도 처리해야 합니다.

비동기 작업 오류 코드

Midjourney 작업

`code`	HTTP 상태	사용자 관점의 의미	권장 처리
`1`	`200`	작업 제출 성공	반환된 작업 ID를 보관하고 조회 API로 진행 상황을 확인합니다
`4`	`400`	요청 매개변수 오류	Prompt, 작업 유형 및 필수 필드를 확인합니다
`21`	`200`	동일한 작업이 이미 있음	반환된 작업 ID를 계속 사용하며 중복 생성하지 않습니다
`22`	`200`	작업이 대기 중	작업 ID를 보관하고 나중에 다시 조회합니다
`23`	`429`	현재 작업 대기열이 가득 참	제출 빈도를 낮추고 나중에 재시도합니다
`24`	`400`	Prompt가 콘텐츠 검사를 통과하지 못함	Prompt를 수정한 후 다시 제출합니다
`3`	`403`	요청을 일시적으로 제출할 수 없음	오류 정보를 보관하고 나중에 재시도하거나 기술 지원에 문의합니다
`30`	`429`	현재 그룹의 처리 용량 한도 도달	동시 요청을 줄이고 나중에 재시도합니다

작업 제출 성공 예시:

{
  "code": 1,
  "description": "제출 성공",
  "result": "TASK_ID"
}

작업 대기 예시:

{
  "code": 22,
  "description": "대기 중이며 앞에 작업 2개가 있습니다"
}

플랫폼 작업

`code`	HTTP 상태	사용자 관점의 의미	권장 처리
`task_not_exist`	`404`	작업이 없거나 현재 계정에 속하지 않음	작업 ID, API 키 및 요청 노드를 확인합니다
`quota_not_enough`	`403`	작업 생성에 필요한 할당량 부족	계정과 토큰 할당량을 확인하고 그대로 재시도하지 않습니다
`invalid_api_platform`	`400`	요청의 플랫폼 타입이 유효하지 않음	플랫폼 또는 프로토콜 매개변수를 수정합니다
`fail_to_fetch_task`	상위 서비스 상태 기준	작업 원본에서 최신 상태를 가져올 수 없음	현재 작업 ID를 보관하고 나중에 제한적으로 재시도합니다

플랫폼 프로그램 오류 코드

`code`	일반적인 HTTP 상태	사용자 관점의 의미	권장 처리
`invalid_request`	`400`	유효하지 않은 요청 형식 또는 매개변수	JSON, 필수 필드 및 필드 타입을 확인합니다
`read_request_body_failed`	`400`	요청 본문을 읽을 수 없음	요청 본문 크기, 연결 및 Content-Type을 확인합니다
`sensitive_words_detected`	`400`	입력이 콘텐츠 검사를 통과하지 못함	입력을 수정한 후 다시 보냅니다
`prompt_blocked`	`400`	콘텐츠 정책이 Prompt를 차단함	오류 정보에 따라 Prompt를 수정합니다
`access_denied`	`403`	요청이 거부됨	API 키, 계정 상태 및 허용 IP 범위를 확인합니다
`insufficient_user_quota`	`403`	계정의 가용 할당량 부족	잔액이나 할당량을 확인한 후 요청합니다
`pre_consume_token_quota_failed`	`403`	Token 가용 할당량 부족	현재 키의 할당량과 사용 제한을 확인합니다
`model_not_found`	`404`	현재 계정에서 대상 모델을 찾을 수 없음	모델 목록에서 사용 가능한 모델 ID를 다시 복사합니다
`convert_request_failed`	`500`	요청을 대상 프로토콜로 변환할 수 없음	Endpoint, 프로토콜 및 대상 모델의 호환성을 확인합니다
`count_token_failed`	`500`	요청의 Token 사용량을 계산할 수 없음	마스킹된 요청 특성과 Request ID를 보관합니다
`do_request_failed`	`500`	플랫폼이 상위 서비스 요청을 완료할 수 없음	네트워크 상태를 확인하고 제한적으로 재시도합니다
`bad_response_status_code`	상위 서비스 상태 기준	상위 서비스가 비표준 또는 직접 파싱할 수 없는 오류를 반환함	원래 HTTP 상태, 마스킹된 메시지 및 Request ID를 보관합니다
`api_not_implemented`	`501`	현재 Endpoint를 아직 사용할 수 없음	API 레퍼런스를 확인하고 이미 공개된 Endpoint를 사용합니다

클라이언트 처리 원칙

HTTP 상태, 프로그램 오류 코드, 마스킹된 메시지 및 Request ID를 함께 기록합니다.
400、401、403은 원인을 먼저 수정하며 그대로 자동 재시도하지 않습니다.
404는 경로와 리소스 ID를 확인하고 비동기 리소스는 소유 계정도 확인합니다.
429、502、503、504는 제한된 횟수의 백오프 재시도를 사용할 수 있습니다.
작업 생성 또는 부수 효과가 있는 요청은 다시 보내기 전에 원래 요청의 적용 여부를 확인합니다.
오류 메시지의 전체 문구로 분기하지 말고 안정적인 HTTP 상태와 code를 우선 사용합니다.

추적 정보 보관은 Request ID를 참고하고, 자세한 문제 해결 및 재시도 권장 사항은 오류 및 문제 해결을 확인합니다.