API Reference
오류
요청 오류와 실패한 이미지 작업을 해석합니다.
오류 읽는 법
HTTP 상태 코드는 API로 보낸 요청 자체를 설명하고, error.code는 실패 원인을 설명합니다. 둘은 서로 다른 필드입니다: HTTP 200은 비즈니스 오류 코드가 아닙니다.
- 거부된 제출은 HTTP 오류 상태 코드와
error객체를 반환합니다. - 성공한 작업 조회는 HTTP 200을 반환합니다. 생성이
processing,completed,failed중 어느 상태인지는status로 판단하세요. - 실패한 작업에서는
message의 문구가 아니라error.code로 분기하세요. 실패 원인이 다르면 코드도 다르며, 같은 원인에는 모델이 달라도 같은 코드가 사용됩니다. - 더 구체적인 공개 원인을 특정할 수 없을 때는
60002로 대체됩니다. 앞으로 추가될 미확인 코드는 일반적인 실패로 처리하세요.
아래 표의 오류 코드와 메시지는 API가 그대로 반환하는 문자열이므로 영문 원문을 유지합니다. 클라이언트가 실제로 받는 error.message와 한 글자도 다르지 않습니다.
Request errors
These HTTP statuses describe a rejected or unconfirmed submission, or a failed task query. A submission timeout does not prove that no task was created.
Error code (error.code) | HTTP status | Meaning | Next step |
|---|---|---|---|
10001 | 401 | The API key is missing or invalid. | Check the Authorization header and API key. |
10002 | 403 | You do not have permission to make this request. | Check access permissions. |
20001 | 400, 413, 422 | The request was rejected. Check the parameters against the API documentation. | Correct the request parameters before retrying. |
20002 | 400 | The requested model is not available. | Select a model listed in the model catalog. |
30001 | 402 | Not enough credits to run this request. | Add credits before submitting. |
30002 | 429 | Too many requests. Please wait and try again. | Wait and retry with backoff. Do not repeat accepted submissions. |
50001 | 404 | Task not found. | Check the task ID and use the owning account’s key. |
50002 | 503 | Submission could not be confirmed. Check your tasks before submitting again. | Check task history before submitting again; the request may have been accepted. |
90001 | 503 | The service is temporarily unavailable. | Back off; retain any task ID already received. |
Task failures
A successful task query returns HTTP 200 even when generation failed. Check status: "failed" and error.code in the response. These codes describe the task outcome, not the HTTP request. Failed tasks are not charged.
Error code (error.code) | Meaning | Next step |
|---|---|---|
20001 | The request was rejected. Check the parameters against the API documentation. | Correct the request parameters before retrying. |
50003 | The task did not complete within the allowed time. Please try again. | The task is not charged. You may submit a new task. |
60001 | The request was rejected by the content policy. Please revise the prompt or input images. | Revise the prompt or media input. |
60002 | Generation could not be completed. Please try again. | The task is not charged. You may submit a new task. |
60003 | No output was generated. Please revise the prompt or try again. | Revise the input or submit a new task. |
60004 | The generated output could not be delivered. Please try again. | The task is not charged. Try again later. |
90001 | The service is temporarily unavailable. | Back off; retain any task ID already received. |
{
"id": "task_...",
"status": "failed",
"error": {
"code": 60002,
"message": "Generation could not be completed. Please try again."
}
}제출 자체가 타임아웃된 경우에는 다시 보내기 전에 작업 내역을 확인하세요. 첫 번째 요청이 이미 접수되었을 수 있습니다.