오류

• API 요청 오류 — 동기 API 호출에 대한 HTTP 응답입니다(인증, 결제, 잘못된 형식의 요청, 존재하지 않는 리소스 등). API 요청 오류를 참고하세요.
• Prediction 실패 코드 — 요청은 접수되어 대기열에 들어갔지만, prediction 자체가 status: "failed"로 끝난 경우입니다. 실패 내용은 prediction의 error 객체로 설명되며, prediction 상태 엔드포인트, webhook 전달, 그리고 result 엔드포인트를 통해 받을 수 있습니다. Prediction 실패 코드를 참고하세요.

​

Prediction 실패 코드

{
  "status": "failed",
  "error": {
    "code": "internal_server_error",
    "reason": "provider_account_error",
    "retryable": false,
    "message": "This model is temporarily unavailable due to an upstream account issue on our side. Retrying will not help; we have been alerted."
  }
}

​

오류가 전달되는 곳

​

result 엔드포인트에서 실패 읽기

{
  "error": {
    "type": "invalid_request_error",
    "code": "PREDICTION_FAILED",
    "message": "The prediction may contain sensitive or restricted content and has been suppressed. Please revise your input.",
    "details": {
      "code": "unsafe_content",
      "message": "The prediction may contain sensitive or restricted content and has been suppressed. Please revise your input.",
      "reason": "moderation_blocked",
      "retryable": false,
      "timestamp": "2026-08-14T17:51:47.206Z"
    }
  },
  "request_id": "req_01JXQ2ZK8W3P5N7V0T6Y4M9DQR",
  "timestamp": "2026-08-17T09:00:00.000Z",
  "path": "/v1/queue/requests/pd_a839exsaLNmVZzWvDaxAuapS"
}

• error.code는 PREDICTION_FAILED로, “출력을 요청한 그 prediction이 출력을 만들어 내지 못했다”는 뜻의 API 요청 오류입니다.
• error.details는 prediction 자체의 error 객체입니다 — 같은 요청에 대해 /status가 보고하는 내용과 동일하므로, 두 엔드포인트가 실패 원인을 두고 서로 다른 말을 할 수 없습니다. 분기는 error.details.reason과 error.details.retryable로 하세요.

​

재시도 여부 판단하기

​

code

​

reason

​

input_validation_failed

​

provider_rejected_input

​

input_fetch_failed

• false — 상대 호스트가 저희를 거부한 경우: 4xx, 저희가 가져올 수 없는 주소, 리다이렉트, 또는 크기 제한을 넘는 파일.
• true — 상대 호스트에 일시적으로 도달할 수 없었던 경우: 5xx, 타임아웃, 또는 DNS 실패.

{
  "code": "invalid_input",
  "reason": "input_fetch_failed",
  "retryable": false,
  "message": "Failed to fetch the input file at https://media.example.com/uploads/reference.png: HTTP 403."
}

​

moderation_blocked

​

provider_rate_limited

​

provider_unavailable

​

provider_timeout

​

provider_account_error

​

endpoint_misconfigured

​

queue_enqueue_failed

​

reaped_stalled

​

알 수 없는 값

• 알 수 없는 reason — reason이 없는 것으로 간주하고 retryable(또는 code별 기본값)로 판단하세요. 원본 값은 로그에 남겨 두세요. 지원팀이 실패를 특정하는 가장 빠른 단서입니다.
• 알 수 없는 code — internal_server_error로 간주하세요. 이름을 알아 둘 만한 센티널 값이 하나 있습니다. unknown_error_code는 prediction이 실패했지만 그에 대한 분류를 전혀 복원할 수 없을 때 Sunra가 내보내는 값입니다.

​

마이그레이션 안내: 오류가 없을 때 error는 null입니다

• prediction이 실패하지 않았을 때 error는 null입니다. GET /v1/predictions/{prediction_id}는 이전에는 succeeded, queued, cancelled 상태의 모든 prediction에 대해 빈 객체 "error": {}를 반환했습니다. 이제는 "error": null을 반환하며, 이는 queue status 엔드포인트가 이미 해 오던 방식입니다. 비어 있는지를 검사하고 있다면(Object.keys(response.error).length === 0), null 검사(response.error === null)로 바꾸세요.
• 실패에는 언제나 비어 있지 않은 code와 message가 함께 옵니다. 실패가 기록한 내용을 저희가 분류할 수 없는 경우, 없거나 비어 있거나 문자열이 아닌 필드 대신 센티널 값 unknown_error_code와 일반적인 message를 받게 됩니다.
• 일반 텍스트로 기록된 실패도 텍스트 그대로 전달됩니다. 2026년 4월의 일부 prediction은 오류를 문자열 하나로만 저장했습니다. GET /v1/predictions/{prediction_id}는 이전에는 그것을 버렸고, queue status 엔드포인트는 센티널 message로 대체했습니다. 이제는 두 곳 모두 그 내용을 code: "unknown_error_code" 아래의 message로 게시합니다.

​

예정된 변경: 일부 실패에 더 구체적인 code가 부여됩니다

• 공급자가 결정론적으로 입력을 거부한 경우는 invalid_input이 됩니다(이전에는 service_provider_error);
• 잘못 설정된 엔드포인트나 저희의 공급자 계정 문제처럼 Sunra 측 문제는 internal_server_error가 됩니다(이전에는 service_provider_error);
• 가져오지 못한 입력 파일은 invalid_input이 됩니다(이전에는 internal_server_error).

​

API 요청 오류