REST API

응답과 오류

모든 API의 HTTP 상태 코드, 오류 코드와 Job 상태를 한곳에서 확인하세요.

성공 응답 · HTTP 응답과 오류 · Job 상태 · Job 오류 · 취소 결과

HTTP status는 요청 처리 결과이며, 응답 본문의 status는 Job 실행 상태입니다. HTTP 200이어도 Job은 failed 또는 canceled일 수 있습니다.

성공 응답

202 Accepted는 작업이 접수되었다는 뜻이며 완료를 의미하지 않습니다. 200 OK는 조회 또는 취소 요청이 처리되었다는 뜻입니다. Job의 status나 취소 결과의 results[].status를 함께 확인하세요. 성공 응답에는 공통 최상위 code 필드가 없습니다.

HTTP status	API
`202 Accepted`	Job 생성
`200 OK`	Job 목록 조회
`200 OK`	Job 상태와 결과 조회
`200 OK`	Job 취소
`200 OK`	Job 전체 취소
`200 OK`	전체 ComfyUI node 정보 조회
`200 OK`	특정 ComfyUI node 정보 조회

HTTP 응답과 오류

Nordy 요청 오류는 최상위 code, message, requestId로 반환됩니다. 문의할 때 requestId를 함께 전달하세요. 같은 code라도 HTTP status와 API에 따라 의미가 다를 수 있습니다.

JSON

{
  "statusCode": 400,
  "code": "INVALID_INPUT",
  "message": "The request is invalid.",
  "requestId": "request-id",
  "details": {
    "field": "prompt"
  }
}

아래 표는 각 API 레퍼런스의 응답 정의를 모은 것입니다. —는 공통 오류 code가 정의되지 않은 응답입니다. 304는 오류가 아니며 응답 본문이 없습니다. 노드 정보 API의 기타 응답은 ComfyUI가 반환하는 상태와 본문에 따라 달라질 수 있습니다.

HTTP status	code	의미 / 확인할 내용	API
`304`	—	ETag가 일치하며 body는 없습니다.	전체 ComfyUI node 정보 조회
`304`	—	조건부 요청을 지원하며 ETag가 일치하면 응답 본문 없이 반환됩니다.	특정 ComfyUI node 정보 조회
`400`	`INVALID_JSON`, `INVALID_INPUT`	JSON, prompt 또는 metadata가 유효하지 않습니다.	Job 생성
`400`	`MULTIPLE_AUTH_CREDENTIALS`	로그인 쿠키를 제외하고 api-key header만 보내세요.	Job 생성, Job 목록 조회, Job 상태와 결과 조회, 전체 ComfyUI node 정보 조회, 특정 ComfyUI node 정보 조회
`400`	`INVALID_INPUT`	limit 또는 cursor가 유효하지 않습니다.	Job 목록 조회
`400`	`INVALID_INPUT`	id가 24자리 16진수 문자열 형식이 아닙니다.	Job 상태와 결과 조회
`400`	`INVALID_JSON`, `INVALID_INPUT`	올바른 job_ids 배열을 전달하세요.	Job 취소
`400`	`MULTIPLE_AUTH_CREDENTIALS`	로그인 쿠키를 제외하고 API 키만 보내세요.	Job 취소, Job 전체 취소
`400`	`INVALID_INPUT`	className이 유효한 단일 path segment가 아닙니다.	특정 ComfyUI node 정보 조회
`401`	`AUTHENTICATION_REQUIRED`	API key가 없거나 일치하지 않습니다.	Job 생성, Job 목록 조회, Job 상태와 결과 조회, 전체 ComfyUI node 정보 조회, 특정 ComfyUI node 정보 조회
`401`	`AUTHENTICATION_REQUIRED`	API 키가 없거나 유효하지 않습니다.	Job 취소, Job 전체 취소
`402`	`INSUFFICIENT_CREDIT`	Job을 생성할 credit이 부족합니다.	Job 생성
`403`	`USER_SUSPENDED`, `PRO_SUBSCRIPTION_REQUIRED`, `INVALID_INPUT`	계정이 정지되었거나, Pro 구독이 활성화되어 있지 않거나, API 이용이 제한된 상태입니다.	Job 생성, Job 목록 조회, Job 상태와 결과 조회, 전체 ComfyUI node 정보 조회, 특정 ComfyUI node 정보 조회
`403`	`USER_SUSPENDED`, `PRO_SUBSCRIPTION_REQUIRED`, `INVALID_INPUT`	계정이 정지되었거나 Pro 구독이 없거나 API 이용이 제한되었습니다.	Job 취소, Job 전체 취소
`404`	`JOB_NOT_FOUND`	존재하지 않거나 다른 사용자 소유이거나 Comfy prompt API로 생성한 Job이 아닙니다.	Job 상태와 결과 조회
`413`	`REQUEST_BODY_TOO_LARGE`	JSON body가 최대 크기인 50 MiB를 초과했습니다.	Job 생성
`413`	`REQUEST_BODY_TOO_LARGE`	JSON 본문이 50 MiB를 초과했습니다.	Job 취소
`415`	`UNSUPPORTED_MEDIA_TYPE`	Content-Type이 application/json이 아닙니다.	Job 생성
`415`	`UNSUPPORTED_MEDIA_TYPE`	Content-Type: application/json으로 요청하세요.	Job 취소
`429`	`DAILY_JOB_LIMIT_EXCEEDED`	생성 한도에 도달했습니다. 초기화된 후 다시 시도하세요.	Job 생성
`500`	`INTERNAL_ERROR`	서버 내부 오류입니다.	Job 생성, Job 목록 조회, Job 상태와 결과 조회
`500`	`INTERNAL_ERROR`	요청 처리 중 오류가 발생했습니다. 작업 상태를 확인한 뒤 다시 시도하세요.	Job 취소
`500`	`INTERNAL_ERROR`	요청 처리 중 서버 오류가 발생했습니다.	Job 전체 취소, 전체 ComfyUI node 정보 조회, 특정 ComfyUI node 정보 조회
`502 / 504`	`INTERNAL_ERROR`	서비스에 연결하지 못했거나 응답 대기 시간이 초과되었습니다.	전체 ComfyUI node 정보 조회, 특정 ComfyUI node 정보 조회
`Other`	—	ComfyUI에서 반환하는 다른 상태 코드와 응답 본문이 포함될 수 있습니다.	전체 ComfyUI node 정보 조회, 특정 ComfyUI node 정보 조회

Job 상태

생성·단건 조회 응답의 status, 목록 조회의 jobs[].status에 사용됩니다.

status	의미	다음 단계
`queued`	대기 중이거나 실행을 준비하고 있습니다.	`Retry-After`를 따라 다시 조회하세요. 실행 준비가 시작되면 취소할 수 없습니다.
`processing`	작업이 실행 중입니다.	`Retry-After`를 따라 다시 조회하세요.
`succeeded`	작업이 성공했습니다.	`outputs`의 파일을 만료 전에 내려받으세요. 모든 결과가 만료되면 `outputs: []`입니다.
`failed`	작업이 실패했습니다.	`error.code`와 `error.message`를 확인하세요.
`canceled`	작업이 취소되었습니다.	`error.code`는 `JOB_CANCELED`입니다.

Job 오류

요청 자체의 오류 code와 별개로, Job의 error.code에 반환됩니다. 목록 조회에서는 jobs[].error.code를 확인하세요. failed·canceled 외 상태의 error는 null입니다.

status	error.code	의미 / 확인할 내용
`failed`	`INVALID_INPUT`	노드 입력값과 모델 이름을 확인하세요. `error.details.node_errors`에 노드별 유효성 검사 결과가 포함될 수 있습니다.
`failed`	`INSUFFICIENT_CREDIT`	크레딧 잔액을 확인한 뒤 새 작업을 만드세요.
`failed`	`EXECUTION_TIMEOUT`	작업 실행 시간이 초과되었습니다. 오류 메시지를 확인하세요.
`failed`	`WORKER_UNAVAILABLE`	작업을 실행할 수 없는 상태입니다. 오류 메시지를 확인하고 계속 발생하면 고객 지원에 문의하세요.
`failed`	`EXECUTION_FAILED`	작업 실행 중 오류가 발생했습니다. 오류 메시지를 확인하세요.
`canceled`	`JOB_CANCELED`	작업이 취소되었습니다.

취소 결과

Job 취소는 HTTP 200이어도 ID별 결과가 다를 수 있습니다. results[].status를 확인하세요. Job 전체 취소는 canceled_count만 반환합니다.

results[].status	의미
`canceled`	이번 요청으로 취소되었습니다.
`already_canceled`	이미 취소된 작업입니다.
`not_cancelable`	실행 준비가 시작되었거나 이미 종료된 작업입니다.
`not_found`	작업이 없거나, 다른 계정 소유이거나, 이 API로 생성한 작업이 아닙니다.

알려지지 않은 오류 코드도 보존하세요. 생성 요청이 시간 초과되거나 응답이 끊기면 다시 제출하기 전에 재시도와 시간 초과를 확인하세요.