API 참조 문서
오류
오류 응답 구조, 전체 오류 코드 및 재시도 시점.
응답 구조#
{
"error": {
"code": "INSUFFICIENT_CREDITS",
"message": "Not enough credits.",
"request_id": "a698a9af-0685-4557-9b29-ca57637748f9",
"details": { "top_up_url": "https://scifig.ai/pricing?utm_source=api" }
}
}분기는 error.code 및 details.reason으로 판단하고, 변경될 수 있는 message는 사용하지 마세요. 응답에 내부 진단 정보는 포함되지 않습니다.
코드#
| 코드 | HTTP | 의미 | 재시도 |
|---|---|---|---|
| UNAUTHORIZED | 401 | 인증 정보가 없거나 유효하지 않습니다. | 아니요. 요청을 변경하거나 새 키 사용 |
| ACCOUNT_UNAVAILABLE | 401 | 이 계정은 API를 사용할 수 없습니다. | 아니요. 요청을 변경하거나 새 키 사용 |
| SCOPE_DENIED | 403 | 이 인증 정보에는 해당 권한이 없습니다. | 아니요. 요청을 변경하거나 새 키 사용 |
| INVALID_REQUEST | 400 | 요청이 유효하지 않습니다. | 아니요. 요청을 변경하거나 새 키 사용 |
| IDEMPOTENCY_KEY_REQUIRED | 400 | Idempotency-Key 헤더(출력 가능한 ASCII 문자 1–255자)가 필요합니다. | 아니요. 요청을 변경하거나 새 키 사용 |
| IDEMPOTENCY_CONFLICT | 409 | 이 Idempotency-Key는 이미 다른 요청에 사용되었습니다. | 아니요. 요청을 변경하거나 새 키 사용 |
| IDEMPOTENCY_IN_PROGRESS | 409 | 이 Idempotency-Key의 요청은 아직 처리 중입니다. | 예, 동일한 Idempotency-Key 사용 |
| NOT_FOUND | 404 | 찾을 수 없습니다. | 아니요. 요청을 변경하거나 새 키 사용 |
| REVISION_CONFLICT | 409 | 현재 그래프 또는 순서도 작업을 편집할 수 없습니다: NOT_LATEST_REVISION, EDIT_IN_PROGRESS 또는 상위 작업이 실행 중인 경우의 PARENT_JOB_RUNNING. | PARENT_JOB_RUNNING인 경우에만 Retry-After 후 같은 키로 재시도. 그 외에는 새 키로 최신 버전 편집 |
| PAYLOAD_TOO_LARGE | 413 | 요청 본문이 너무 큽니다. | 아니요. 요청을 변경하거나 새 키 사용 |
| INSUFFICIENT_CREDITS | 402 | 크레딧이 부족합니다. | 아니요. 요청을 변경하거나 새 키 사용 |
| CONTENT_REJECTED | 422 | 콘텐츠 정책이 요청을 거부했습니다. 생성 시에는 422, 실행 중이면 실패 작업의 error.code로 반환하며, 두 경우 모두 환불됩니다. | 아니요. 프롬프트 또는 입력을 변경하고 새 키 사용 |
| PLAN_REQUIRED | 403 | 현재 요금제에는 이 옵션이 포함되지 않습니다. | 아니요. 요청을 변경하거나 새 키 사용 |
| RATE_LIMITED | 429 | 요청 수, 시간당 작업 수, 일일 변환 수 또는 업로드 수를 초과했습니다. details.reason이 해당 원인을 표시합니다. | 예, 동일한 Idempotency-Key 사용 |
| CONCURRENCY_LIMITED | 429 | 이 계정에서 실행 중인 작업이 너무 많습니다. | 예, 동일한 Idempotency-Key 사용 |
| SERVICE_UNAVAILABLE | 503 | 서비스를 일시적으로 사용할 수 없습니다. 같은 Idempotency-Key로 재시도하세요. | 예, 동일한 Idempotency-Key 사용 |
| TASK_FAILED | 502 | 작업이 실패하여 크레딧이 환불되었습니다. 다시 시도하려면 새 Idempotency-Key로 새 요청을 보내세요. | 아니요. 요청을 변경하거나 새 키 사용 |
| INTERNAL_ERROR | 500 | 내부 오류. | 예, 동일한 Idempotency-Key 사용 |
INVALID_REQUEST에는 관련 정보가 있는 경우 details.reason, details.field 또는 details.issues가 포함될 수 있습니다. 본문이 한도(JSON 256 KB, 업로드는 파일별 한도)를 초과하면 413 PAYLOAD_TOO_LARGE를 반환합니다. details.top_up_url은 INSUFFICIENT_CREDITS에만 포함됩니다. 작업이 생성된 뒤 생성 요청이 실패하면(429, 503, 409 IDEMPOTENCY_IN_PROGRESS 또는 500 INTERNAL_ERROR), details.job_id가 해당 작업을 가리킵니다. 같은 Idempotency-Key로 재시도하거나 GET /jobs/{job_id}를 폴링하고, 새 키는 사용하지 마세요.
실패한 작업 내부의 코드#
생성된 뒤 실패한 작업은 status: "failed"와 error 객체를 보고합니다. 거부된 요청에 대한 위 코드 외에 error.code는 다음 값일 수 있습니다:
| error.code | 의미 | 대처 방법 |
|---|---|---|
| TASK_TIMED_OUT | 작업 시간이 초과되어 환불되었습니다. 과학 그림 생성 또는 편집에 late_delivery_until이 포함되면 해당 시각까지 무료로 결과가 도착할 수 있습니다. | late_delivery_until까지 작업을 계속 조회. 그 외에는 새 키로 새 요청 전송 |
| CONTENT_REJECTED | 작업 실행 중 콘텐츠 정책이 결과를 거부했으며 환불되었습니다. 생성 시 요청 자체가 거부되면 같은 코드를 422로 반환합니다. | 프롬프트 또는 입력을 변경하고 새 키 사용 |
| ADMISSION_INCOMPLETE | 재시도 가능한 오류로 작업이 시작되지 않았습니다. 크레딧은 사용하지 않았습니다. | 같은 요청을 같은 Idempotency-Key로 전송 |
| TASK_NOT_FOUND | 작업이 접수되었지만 해당 작업 데이터를 더 이상 찾을 수 없습니다. | 새 키로 새 요청 전송 |
| TASK_FAILED | 작업이 실패하여 환불되었습니다. 별도 공개 코드가 없는 모든 엔진 장애는 TASK_FAILED로 표시하며, 엔진 코드는 details.reason에 포함됩니다. | 새 키로 새 요청 전송 |
| INTERNAL_ERROR | 작업이 이유를 보고하지 않고 실패했으며 환불되었습니다. | 새 키로 새 요청 전송 |
429 발생 원인#
- 요청 수 초과: 생성은 인증 정보별 분당 20건, 계정별 40건, 조회는 인증 정보별 분당 120건입니다.
Retry-After는 제한 구간 초기화까지의 시간이며,details.reason은 없습니다. - 최근 1시간 동안 시작한 작업 수 초과: 계정별 최대 200건, 웹사이트와 공유.
Retry-After: 30. - 실행 중인 작업 수 초과:
429 CONCURRENCY_LIMITED. 요금제별 한도를 웹사이트와 공유(GET /credits참조).Retry-After: 30. - 무료 PNG, PDF, TIFF 및 PPTX 변환의 일일 200회 한도를 소진했습니다.
details.reason = DAILY_CONVERSION_LIMIT와 일일 제한 구간 초기화까지의Retry-After를 반환합니다. - 업로드 빈도 초과:
details.reason = UPLOAD_RATE_LIMITED.POST /files의 이미지 및 마스크, 순서도 첨부 파일, 그래프 데이터에 웹사이트의 분당 업로드 한도를 적용합니다. - 일일 업로드 수 초과:
details.reason = UPLOAD_DAILY_LIMIT_REACHED. 순서도 첨부 파일과 그래프 데이터에 웹사이트의 일일 업로드 한도를 적용합니다. - 텍스트 감지: 계정별 15분당 20회, 웹사이트와 공유.