API 가이드

오류

Markdown으로 보기 업데이트됨 2026-10-22

모든 엔드포인트는 동일한 방식으로 실패합니다. HTTP 상태 코드와 하나의 JSON 봉투를 반환합니다.

JSON

{
  "error": {
    "type": "invalid_request",
    "code": "invalid_input",
    "message": "duration must be one of 5, 10.",
    "param": "duration",
    "details": [ { "param": "duration", "message": "duration must be one of 5, 10." } ],
    "request_id": null,
    "doc_url": "https://doitong.com/developers/docs/errors#invalid_input"
  }
}

필드	의미
`type`	오류의 광범위한 분류입니다. 이를 바탕으로 처리 방법을 결정합니다.
`code`	정확한 원인으로, 안정적이며 기계가 읽을 수 있습니다. 모든 코드에는 아래에 섹션이 있으며 `doc_url`이 해당 섹션으로 연결됩니다.
`message`	개발자에게 로그로 기록하거나 표시해도 안전한 사람이 읽을 수 있는 설명입니다.
`param`	문제가 있는 입력 매개변수 또는 헤더입니다. 해당하는 경우에만 포함됩니다.
`details`	입력 오류의 경우 발견된 모든 문제입니다: `[{ "param", "message" }]`.
`request_id`	관련 요청입니다. 존재하는 경우에만 포함됩니다.

오류를 반환하는 호출에는 요금이 부과되지 않습니다. 수락된 후 실패한 요청은 상태가 failed로 유지되고, 요청 객체에 error: { "type", "code", "message" }가 포함되며, 자동으로 환불됩니다.

유형

유형	HTTP 상태	처리 방법
`invalid_request`	400, 413 또는 422	요청을 수정합니다. 동일한 호출을 다시 시도해도 다시 실패합니다.
`authentication_error`	401	`Authorization: Bearer <key>`에 유효한 키를 보냅니다.
`permission_error`	403	필요한 scope가 있는 키를 사용합니다.
`not_found`	404	모델 id 또는 요청 id를 확인합니다.
`insufficient_credits`	402	API 잔액을 충전합니다(오류의 `top_up_url`).
`budget_exceeded`	402	키 자체의 한도를 모두 사용했습니다. 최종 조치: 키 소유자에게 한도 상향을 요청합니다.
`conflict`	409	리소스가 이 호출을 허용하는 상태가 아닙니다.
`rate_limited`	429	`Retry-After`초 동안 기다린 다음 다시 시도합니다.
`upstream_error`	502	모델 백엔드가 실패했습니다. 동일한 `Idempotency-Key`로 다시 시도해도 안전합니다. 다시 실행되며 요금은 부과되지 않습니다.
`service_unavailable`	503	API가 일시 중지되었거나 종속 서비스가 중단되었습니다. 나중에 다시 시도합니다.
`internal_error`	500	저희 측의 버그입니다. 다시 시도하고, 계속되면 시간과 `request_id`를 함께 지원팀에 문의합니다.

코드

`invalid_request`

형식이 잘못된 일반 요청입니다(400).

`invalid_json`

본문이 유효한 JSON이 아닙니다(400).

`invalid_body`

본문은 유효한 JSON이지만 객체가 아닙니다. 모델 입력은 JSON 객체여야 합니다(400).

`body_too_large`

본문이 16 MB보다 큽니다(413). 큰 파일을 업로드하고 대신 URL을 전달합니다(파일 참조).

`invalid_parameter`

쿼리 매개변수의 값이 잘못되었습니다. 예를 들어 limit이 1~100 범위를 벗어났거나, wait가 숫자가 아니거나, 알 수 없는 status 또는 category이거나, storage가 permanent / temporary 이외의 값인 경우입니다(400). param에 해당 이름이 표시됩니다.

`invalid_category`

GET /openapi.json?category=가 존재하지 않는 category를 지정합니다(400). GET https://api.doitong.ru/v1/categories에 목록이 표시됩니다.

`invalid_cursor`

목록 호출의 cursor가 이 목록에 속하지 않습니다(400). cursor 없이 다시 시작합니다.

`invalid_idempotency_key`

Idempotency-Key 헤더가 비어 있거나 255자를 초과합니다(400).

`invalid_arguments`

MCP 도구 호출에 누락되었거나 형식이 잘못된 인수가 있습니다(MCP만 해당). param에 인수 이름이 표시됩니다.

`invalid_input`

모델 입력이 검증을 통과하지 못했습니다(422). 알 수 없는 매개변수(메시지에 가장 가까운 유효한 이름이 제안됨), 필수 매개변수 누락, 잘못된 유형, 허용된 목록 또는 범위를 벗어난 값, 또는 표준 이름과 네이티브 이름이 서로 다른 값으로 함께 지정된 경우입니다. param은 처음 발견된 문제가 있는 매개변수이며 details에 모든 문제가 표시됩니다. 요금은 부과되지 않습니다.

`unsupported_file`

파일 유형을 허용하지 않습니다(422). 예를 들어 지원되지 않는 확장자로 업로드했거나 content_type이 확장자와 일치하지 않는 경우입니다.

`invalid_webhook_url`

webhook_url이 공개 https:// URL이 아닙니다(422). 비공개, 로컬 및 일반 http:// 주소는 거부됩니다.

`missing_api_key`

엔드포인트에 API 키가 필요하지만 전송되지 않았습니다(401).

`invalid_api_key`

키를 알 수 없거나 취소되었거나 만료되었습니다(401).

`insufficient_scope`

키에 이 호출에 필요한 scope가 없습니다(403). 예를 들어 실행에는 models:run이, 요청과 잔액을 읽으려면 models:read가 필요합니다. 인증을 참조하세요.

`account_disabled`

계정이 폐쇄되었거나 정지되었습니다(403). 해당 계정의 키는 더 이상 작동하지 않습니다.

`not_found`

경로가 존재하지 않습니다(404).

`model_not_found`

이 id를 가진 공개 모델이 없습니다(404). GET https://api.doitong.ru/v1/models로 모델을 나열합니다.

`request_not_found`

계정에 이 id를 가진 요청이 없습니다(404). 다른 계정의 요청은 절대 표시되지 않습니다.

`insufficient_credits`

계정의 API 잔액(API 크레딧, 1,000 API 크레딧 = $1 — Doitong 앱의 크레딧과 다름)으로는 이 호출의 가격을 충당할 수 없습니다(402). 요금이 부과되기 전에 응답이 전송됩니다. 오류에 top_up_url이 포함되며, https://doitong.ru/developers/dashboard#balance에서 금액을 추가한 다음 다시 시도합니다.

JSON

{ "error": { "type": "insufficient_credits", "code": "insufficient_credits",
             "message": "This request costs 560 API credits ($0.56); the API balance is 120 API credits ($0.12). Top up at https://doitong.ru/developers/dashboard#balance",
             "top_up_url": "https://doitong.ru/developers/dashboard#balance", "doc_url": "https://doitong.com/developers/docs/errors#insufficient_credits" } }

`budget_exceeded`

호출하면 API 키 자체의 API 크레딧 한도를 초과하게 됩니다(402). 한도는 키 소유자가 설정하며, 소유자가 한도를 높이기 전에는 다시 시도해도 해결되지 않습니다.

`conflict`

호출이 리소스의 현재 상태와 충돌합니다(409).

`idempotency_mismatch`

Idempotency-Key가 이미 다른 본문과 함께 사용되었습니다(409). 새 작업에는 새 키를 사용합니다.

`idempotency_in_progress`

동일한 Idempotency-Key를 사용하는 요청이 지금 생성 중입니다(409). 잠시 후 다시 시도하여 요청을 가져옵니다.

`request_active`

요청이 아직 queued 또는 running 상태이므로 삭제할 파일이 없습니다(409). 요청이 완료된 후 삭제합니다.

`not_cancelable`

요청이 이미 succeeded 또는 failed 상태이므로 취소할 수 없습니다(409).

`rate_limited`

현재 윈도우에 키가 너무 많은 요청을 보냈습니다(429). X-RateLimit-* 및 Retry-After 헤더를 참조하세요.

`too_many_inflight`

계정에 이미 queued 또는 running 상태의 요청이 10개 있습니다(429). 그중 하나가 완료되면 다음 요청을 시작합니다.

`upstream_error`

모델 백엔드가 요청을 거부했거나 실패했습니다(실행 시 502 또는 요청에서 이 코드와 함께 failed). API 크레딧은 환불됩니다. 백엔드 자체가 입력을 거부한 경우에는 대신 메시지와 함께 422 invalid_input이 반환됩니다.

`upstream_lost`

모델 백엔드가 더 이상 요청을 알지 못하므로 결과가 도착하지 않습니다. 이 코드를 포함한 failed 상태 (유형 upstream_error)로 종료되고 환불됩니다. 다시 실행하세요.

`timeout`

요청이 제한 시간(이미지는 15분, 동영상은 60분, 그 외에는 30분)을 초과하여 실행되다가 중지되었습니다. failed 상태와 이 코드로 종료되며 환불됩니다.

`service_unavailable`

API가 일시적으로 중지되었거나 파일 업로드와 같은 종속 서비스가 중단되었습니다(503). 나중에 다시 시도합니다.

`internal_error`

저희 측에서 문제가 발생했습니다(500). 다시 시도하고, 계속되면 지원팀에 문의하세요.

`charge_failed`

내부 문제로 계정에 요금을 청구할 수 없습니다(500). 요청은 failed로 표시되며 요금은 차감되지 않습니다. 다시 시도하세요.

`pricing_unavailable`

모델 가격이 구성되지 않아 지금은 가격을 산정하거나 실행할 수 없습니다(500).

유형#

코드#

invalid_request#

invalid_json#

invalid_body#

body_too_large#

invalid_parameter#

invalid_category#

invalid_cursor#

invalid_idempotency_key#

invalid_arguments#

invalid_input#

unsupported_file#

invalid_webhook_url#

missing_api_key#

invalid_api_key#

insufficient_scope#

account_disabled#

not_found#

model_not_found#

request_not_found#

insufficient_credits#

budget_exceeded#

conflict#

idempotency_mismatch#

idempotency_in_progress#

request_active#

not_cancelable#

rate_limited#

too_many_inflight#

upstream_error#

upstream_lost#

timeout#

service_unavailable#

internal_error#

charge_failed#

pricing_unavailable#

유형

코드