> ## Documentation Index
> Fetch the complete documentation index at: https://docs.toapis.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 오류 코드 빠른 참조

> API 요청 오류와 작업 실패 원인을 확인하고 입력을 수정하거나 불확실한 제출 결과를 복구합니다

요청 실패와 생성 작업 실패를 먼저 구분하세요. `invalid_request` 는 이미지 크기 제한 위반일 수도 있으므로 이미지 입력을 지원하지 않는다는 뜻으로 해석하면 안 됩니다.

## 오류를 읽는 위치

| 상황 | 확인 방법 | 읽을 필드 |
| - | - | - |
| OpenAI 형식 요청 오류 | HTTP 오류 상태 또는 오류 객체 | `error.code`, `error.message`, 선택적 `error.param`, `error.type` |
| 일부 작업 제출/조회 API 의 요청 오류 | HTTP 상태와 응답 본문을 함께 확인 | 최상위 `code`, `message`, `data` |
| 작업 실행 실패 | 조회는 성공했지만 작업 `status` 가 `failed` | `error.code`, 선택적 `error.reason`, `error.message` |
| 작업 Webhook 실패 이벤트 | `type` 이 `generation.failed`, `data.status` 가 `FAILURE` | `data.error.code`, `data.error.message` |
| 동영상 요청 복구 | 복구 기록의 `state` 확인 | 선택적 `error_code`, `message`, `task_id` |

설명용 요청 오류 예시:

```json theme={null}
{
  "error": {
    "code": "invalid_request",
    "type": "toapis_error",
    "param": "",
    "message": "Image dimensions or aspect ratio do not meet this model's requirements."
  }
}
```

작업 실행 실패 예시:

```json theme={null}
{
  "id": "task_example",
  "object": "generation.task",
  "status": "failed",
  "error": {
    "code": "generation_failed",
    "reason": "image_dimensions_multiple",
    "message": "Image dimensions must be multiples of 16."
  }
}
```

예시의 배수는 모든 모델에 적용되는 제한이 아닙니다. HTTP 200 은 조회 성공을 뜻하므로 작업 상태도 확인하세요. 숫자 비즈니스 `code` 역시 HTTP 상태와 다릅니다. `success: false` 응답은 본문을 확인해야 합니다.

`code` 는 오류 식별자, 선택적 `reason` 은 작업 실패 분류, `message` 는 구체적인 설명입니다. `error.type` 이 코드와 같지는 않습니다. 문구는 언어에 따라 바뀌므로 전체 메시지 일치로 로직을 분기하지 마세요. 일부 인증 응답의 `code` 는 비어 있고 일부 프로토콜은 `type`, `message` 만 제공합니다.

## 요청 오류 빠른 참조

공개 요청에서 나올 수 있는 식별자이며 모든 API 가 전부 반환하지는 않습니다. 모델별 원래 표기가 유지될 수도 있습니다. 필드 위치는 위 표를 참고하세요.

| 오류 식별자 | 가능한 원인 | 처리 방법 |
| - | - | - |
| `invalid_request`, `invalid_request_error`, `invalid_params`, `InvalidParameter`, `invalid_parameter_error`, `invalid_value` | 잘못된 자료형, 이미지 크기, 미디어 다운로드, 메시지 구조 또는 매개변수 조합 | `param`, `message` 로 문제 필드를 확인하고 아래 사례에 따라 수정 후 재제출 |
| `invalid_json`, `invalid_multipart_form`, `read_request_body_failed` | JSON/폼 파싱 또는 요청 본문 읽기 실패 | 직렬화, `Content-Type`, 업로드 완료 여부 확인 |
| `unknown_parameter`, `unsupported_value`, `provider_capability_not_supported`, `not_supported` | 모델이 필드, 값, 도구 또는 API 기능을 지원하지 않음 | 정확한 모델 문서 확인. 미지원 필드를 제거하거나 해당 기능을 지원하는 모델 선택 |
| `missing_model`, `model_not_found`, `unsupported_model`, `DeploymentNotFound` | 모델명 누락, 접근 불가, 미지원 API 또는 일시적 서비스 불가 | [모델 목록](https://docs.toapis.com/docs/ko/api-reference/models.md)과 API Key 권한 확인. 이름이 맞고 일시 장애라면 나중에 재시도하거나 지원팀에 문의 |
| `invalid_private_assets`, `invalid_image`, `invalid_image_file` | 잘못된 미디어 참조, 디코딩 불가, 개수/크기 초과 또는 URL 접근 실패 | 해당 미디어와 제한을 확인하고 다시 내보내거나 업로드 |
| `access_denied`, 또는 code 없는 HTTP 401/403 | API Key 무효, 만료, 비활성화 또는 IP/모델 권한 제한 | 키와 권한 확인. 서비스 측 인증 오류가 항상 사용자의 키 문제를 의미하지는 않음 |
| `insufficient_user_quota`, `quota_not_enough`, `token_quota_not_enough`, `pre_consume_token_quota_failed` | 계정 잔액, Token 한도, 기간별 한도 부족 또는 한도 확인의 일시 실패 | 본인 계정/Token 문제라고 명시된 경우에만 충전하거나 한도 변경. 서비스 측 한도나 확인 오류는 나중에 재시도하거나 문의 |
| `rate_limit_exceeded`, `RateLimitReached`, `rate_limit_unavailable` | 요청 빈도 초과, 모델 서비스 제한 또는 한도 확인 불가 | 동시 요청을 줄이고 `Retry-After` 우선 적용 후 지터를 포함한 백오프 사용. [비동기 제한](https://docs.toapis.com/docs/ko/api-reference/rate-limits/async-tasks.md) 참조 |
| `get_channel_failed`, `all_channels_circuit_broken`, `provider_unavailable` | 모델에 사용 가능한 서비스가 없거나 과부하 | 나중에 재시도하고 지속되면 문의. 이미지 내용을 바꿀 필요는 없음 |
| `do_request_failed`, `first_output_timeout`, `up_timeout` | 연결, 첫 출력 또는 응답 읽기 시간 초과. 이미 접수되었을 수 있음 | 작업 ID 가 있으면 먼저 조회. ID 없는 동영상 요청은 아래 복구 절차 사용 |
| `bad_response_status_code`, `bad_response`, `bad_response_body`, `read_response_body_failed`, `upstream_error`, `unknown_error` | 서비스 오류 또는 응답 읽기/파싱 실패 | HTTP 상태와 설명을 확인하고 기존 작업 유무부터 확인. 지속되면 요청 ID 와 함께 문의 |
| `convert_request_failed`, `model_price_error`, `pricing_failed`, `pricing_unavailable`, `internal_error` | 요청 변환, 가격 계산 또는 서비스 처리 실패. 입력 오류가 아닐 수 있음 | 명시된 필드 제약이 있으면 수정, 아니면 나중에 재시도하거나 문의 |
| `task_not_found`, `task_not_exist`, `request_not_found` | 작업/복구 기록 없음, 다른 계정 ID 또는 복구 기록 만료 | ID, 계정, 조회 API 확인. 복구 기록이 없다고 원래 요청이 실행되지 않았다고 단정하지 않기 |
| `invalid_client_request_id`, `request_cache_unavailable`, `submission_unconfirmed` | 복구 ID 오류, 복구 서비스 불가 또는 제출 결과 미확인 | ID 형식을 수정하거나 원래 요청을 기다리며 조회. 새 ID 로 연속 재제출하지 않기 |
| `invalid_callback_url`, `callback_url_origin_mismatch`, `webhook_not_configured`, `webhook_configuration_invalid`, `webhook_configuration_unavailable`, `webhook_configuration_error`, `webhook_api_token_required` | 콜백 URL/Token Webhook 설정 오류 또는 설정 조회 불가 | [작업 Webhook](https://docs.toapis.com/docs/ko/api-reference/webhooks/task-webhooks.md)에서 HTTPS, 출처, API Token, 설정 확인 |
| `sensitive_words_detected`, `prompt_blocked`, `content_policy_violation`, `content_filter`, `content_filtered` | 입력 또는 생성 결과가 콘텐츠 검사를 통과하지 못함 | 프롬프트와 모든 참조 미디어를 확인하고 정책에 맞게 수정. 같은 요청을 자동 반복하지 않기 |
| `invalid_encrypted_content` | 대화 출력 항목의 암호화 콘텐츠를 검증/파싱할 수 없음 | 클라이언트가 이전 출력 항목을 수정/잘랐는지 확인하고 원본 유지. 암호화 내용을 수정하지 말고 지속되면 문의 |

## invalid\_request 의 구체적인 원인

실제 요청과 실패 작업 진단을 정리한 사례입니다. 일반 매개변수 코드, 세부 `reason` 또는 모델 원래 코드로 반환될 수 있습니다. 필드와 설명을 확인한 뒤 수정하세요.

| 구체적인 상황 | 확인 및 수정 방법 |
| - | - |
| 출력 크기 또는 비율 표기 불일치 | 일부 모델의 `size` 는 `1:1` 같은 비율만 받고 다른 모델은 픽셀 크기를 받음. 비율 전용 모델에 `1024x1024` 를 보내면 실패. 해당 모델의 `size`, `resolution`, `aspect_ratio` 정의 준수 |
| 너비, 높이, 총 픽셀 또는 배수 조건 위반 | 너무 작거나 크거나 비율이 과도하거나 지정 배수가 아닐 수 있음. 참조 이미지와 출력 크기를 구분하고 모델 제한에 맞춰 크기 조정/자르기 |
| 참조 파일 크기 또는 개수 초과 | 바이트 수, 긴 변, 총 픽셀, 개수는 별도 제한. 압축해도 픽셀이 줄지는 않으므로 오류에 맞춰 압축, 크기 조정 또는 개수 감소 |
| 이미지 필드 자료형 오류 | URL 문자열 배열이 필요한 API 에 객체 배열을 보낼 수 없음. `image_urls` 와 `image_with_roles` 는 구조가 다르며 일부 API 는 Base64 또는 두 필드 혼용을 거부 |
| URL 은 있지만 서비스가 파일을 읽지 못함 | 403/404, 로그인 필요, URL 만료, 시간 초과, 외부 링크 차단 또는 HTML 응답 확인. 유효 기간이 충분한 공개 직접 다운로드 URL 이나 [업로드 API](https://docs.toapis.com/docs/ko/api-reference/uploads/images.md) 사용 |
| 미지원 미디어 형식 또는 길이 | 확장자가 맞아도 디코딩이 안 될 수 있음. GIF, 동영상 코덱, 프레임률, 개별/총 참조 길이를 모델 문서에 맞춰 다시 내보내기 |
| Seedance 작업 유형과 매개변수 충돌 | 편집으로 판단되면 `aspect_ratio=adaptive`, `duration=-1` 이 필요할 수 있고 연장도 `adaptive` 가 필요할 수 있음. `InvalidParameter.TaskTypeConstraint` 는 다른 유형으로 분류된 경우에도 발생. [Seedance 2.5](https://docs.toapis.com/docs/ko/api-reference/videos/seedance-2-5/generation.md) 참조 |
| 텍스트, 대화 기록 또는 도구 순서 오류 | 프롬프트 초과, 미지원 `developer` 역할, `tool_calls` 에 대응하는 도구 결과 누락, 사고 모드의 `reasoning_content` 누락 등을 모델 규약에 맞춰 수정 |
| 필드는 존재하지만 모델이 받지 않음 | `quality`, `reasoning_effort`, `temperature`, `thinking`, `enable_thinking` 은 공통 지원이 아님. `max_tokens` 와 `max_completion_tokens` 는 동시에 사용할 수 없는 경우가 있음. 도구 Schema 와 `response_format` 도 모델별 제약 확인 |

과거 오류의 수치는 플랫폼 공통 제한이 아닙니다. 이미지 입력 지원 여부는 모델 기능으로 판단하고 `invalid_request`, `invalid_image` 만으로 판단하지 마세요.

## 작업 실패 원인

ID 를 받은 후에는 조회 상태를 기준으로 합니다. 일반 생성 실패는 흔히 `error.code=generation_failed` 를 사용하고 선택적 `error.reason` 이 세부 분류를 제공합니다. 아래 값이 요청 오류의 code 에도 항상 나오는 것은 아닙니다.

`error.input_media_errors` 가 있으면 각 항목의 `type`, `index`, `message` 를 확인하세요. `type=image`, `index=0` 은 원래 요청의 첫 이미지를 뜻하므로 해당 미디어를 수정할 수 있습니다. 모든 모델이나 조회 형식에서 제공되지는 않습니다.

| error.reason | 가능한 원인과 처리 |
| - | - |
| `invalid_input`, `missing_parameter` | 입력이 잘못되었거나 필수 필드 누락. 위의 구체적인 사례와 메시지를 보고 수정 |
| `reference_image_too_large`, `image_dimensions_multiple` | 참조 이미지 파일 크기 또는 픽셀 배수 조건 위반. 바이트 크기와 픽셀 크기를 따로 확인 |
| `reference_media_unreadable`, `unsupported_media_format` | URL 다운로드 실패, 잘못된 파일 또는 미지원 형식. 접근 권한과 실제 미디어 확인 |
| `unsupported_parameter_value`, `parameter_out_of_range`, `parameter_replacement_required` | 허용되지 않는 값, 범위 초과 또는 필드 교체 필요. 메시지와 모델 문서에 따라 수정 |
| `video_edit_parameters_required`, `unsupported_request_capability` | 잘못된 편집 매개변수 조합 또는 미지원 기능. 작업 유형, 매개변수, 모델 변경 |
| `content_policy_rejected` | 프롬프트, 참조 이미지/동영상/오디오 또는 출력이 안전/저작권 검사에 실패. 모든 입력 확인. 적합한 입력도 출력 검사에서 실패할 수 있음 |
| `service_busy`, `request_rate_limited` | 서비스 혼잡 또는 요청 제한. 기다리고 요청 빈도 감소 |
| `generation_timeout` | 생성 또는 처리 시간 초과. 기존 작업부터 확인하고 처리 중인 작업을 중복 생성하지 않기 |
| `generation_unavailable`, `model_unavailable`, `model_region_unavailable` | 모델 서비스 일시 불가 또는 지역 미지원. 모델과 권한 확인 후 지속되면 문의 |
| `insufficient_user_balance`, `token_quota_exceeded` | 본인 계정 잔액 또는 API Token 한도 부족. 양쪽과 기간별 한도 확인 |
| `result_storage_failed` | 결과 저장/전달 실패. 모델이 입력을 지원하지 않는다는 뜻은 아님. 작업 ID 와 함께 문의 |
| `submission_pending_reconciliation` | 제출/생성 결과 확인 대기. 기존 ID 를 유지하고 조회 결과를 기다려 중복 생성 방지 |
| `refund_pending` | 실패 작업 환불 처리 중. 새 조회의 과금 정보를 확인하고 지속되면 문의 |
| `request_cancelled` | 요청 또는 작업 취소. 의도한 취소인지 확인한 뒤 재제출 결정 |
| `generation_failed`, `service_error` | 더 구체적인 공개 원인이 없거나 내부 처리 실패. 작업/요청 ID 를 보관하고 문의 |

일부 모델은 `InvalidParameter.TaskTypeConstraint`, `RateLimitReached`, `InputImageSensitiveContentDetected`, `OutputVideoSensitiveContentDetected` 등의 원래 오류를 유지합니다. 각각 작업 제약, 제한, 입력 검사, 출력 검사와 관련될 수 있으며 전체 목록은 아닙니다.

Seedance Global 조회의 `error.code`, `error.message` 는 숫자나 `null` 을 포함한 원래 JSON 값을 유지하거나 생략할 수 있습니다. OpenAI 동영상 형식과 Webhook 은 `reason` 을 보장하지 않습니다. 알 수 없는 코드, 누락 필드, 다른 자료형을 처리하고 원래 숫자 코드를 HTTP 상태로 해석하지 마세요.

## 재시도와 요청 복구

* 매개변수, 형식, 콘텐츠 검사 문제: 입력을 수정한 뒤 재제출하세요. 같은 요청 반복은 보통 해결책이 아닙니다.
* 제한 또는 일시 불가: `Retry-After` 를 우선 적용하고 없으면 지터를 포함한 지수 백오프와 횟수 제한을 사용하세요.
* 작업 ID 가 있으면 같은 작업을 조회하거나 [작업 Webhook](https://docs.toapis.com/docs/ko/api-reference/webhooks/task-webhooks.md) 을 받으세요. `queued`, `in_progress` 는 실패가 아니므로 중복 작업을 만들지 마세요.
* 동영상 제출 시간 초과 또는 `submission_unconfirmed`: 원래 요청에 `client_request_id` 를 사용했다면 같은 계정으로 `GET /v1/video/requests/{client_request_id}` 를 호출하세요. `task_id` 가 있으면 조회하고 `submitting`, `unknown` 이면 기다리세요. 복구 기록이 `state=failed` 이고 `error_code=submission_rejected` 일 때만 거부가 확인되며 안내에 따라 새 요청을 보낼 수 있습니다. 해당 필드를 사용한 지원 동영상 API 에만 적용됩니다.

작업 실패가 환불 완료를 뜻하지는 않습니다. [과금 안내](https://docs.toapis.com/docs/ko/api-reference/account/pricing.md) 의 제공된 `billing` 필드를 확인하세요. 생략은 무료나 환불 완료를 뜻하지 않습니다. Webhook 은 이벤트 시점 스냅샷이므로 이후 조회와 과금 필드가 다를 수 있습니다.

## 지원팀에 제공할 정보

요청 시각과 시간대, 모델, API 경로, HTTP 상태, 요청 ID, 가능한 작업 ID, code/reason, 민감 정보를 제거한 설명을 제공하세요. 이미지 문제는 크기, 형식, 파일 크기로 충분합니다. API Key, 서명 URL, 전체 프롬프트, 비공개 미디어를 보내지 말고 재현에는 공개 가능한 최소 예시를 사용하세요.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.