오류 - querying.ai

실패는 하나의 봉투를 공유합니다.

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request validation failed",
    "details": [{ "field": "payload.prompt", "message": "payload.prompt or payload.query is required" }],
    "timestamp": "2026-07-09T04:12:00.000Z"
  }
}

code는 안정적이며 분기 조건으로 써도 안전합니다. message는 사람이 읽는 용도이고 바뀔 수 있습니다. details는 문제 필드를 특정할 수 있을 때 포함됩니다.

코드

코드	상태	의미	재시도
`MISSING_API_KEY`	401	Bearer 토큰이 없거나 틀렸습니다.	아니요, 키를 고치세요
`VALIDATION_ERROR`	400	본문 형식 오류, 알 수 없는 `taskType`, 또는 `payload.prompt`와 `payload.query`가 모두 없음.	아니요, 요청을 고치세요
`REGION_UNSUPPORTED`	422	이 엔진은 요청한 `country`를 절대 서빙할 수 없습니다.	아니요, 다른 엔진이나 지역을 고르세요
`REGION_UNAVAILABLE`	422	지금은 이 엔진에서 요청한 `country`에 쓸 용량이 없습니다.	나중에, 용량이 돌아온 뒤
`RESOURCE_ALREADY_EXISTS`	409	단건 엔드포인트에서 `idempotencyKey`가 중복됐습니다.	아니요, 태스크가 이미 있습니다
`PAYLOAD_TOO_LARGE`	413	배치 본문이 8 MB를 넘습니다.	아니요, 더 작게 나눠 보내세요
`RESOURCE_NOT_FOUND`	404	알 수 없는 태스크 id이거나, 24시간 공개 폴링 기간이 지났습니다.	아니요
`ENQUEUE_ERROR`	—	배치 안의 항목별 실패(예: 한 레인의 일시적 DB 문제). HTTP 상태가 아니라 `results[].error`에만 나타납니다.	예

400은 파싱하거나 이해할 수 없는 요청에 씁니다. 422는 형식은 완벽하지만 요청한 지역에서 서빙할 수 없는 요청에만 씁니다. 상태 코드보다 error.code로 분기하는 편이 더 오래 유지됩니다.

지역 거부

두 지역 코드는 모두 태스크를 큐에 넣기 전에 결정됩니다. 태스크가 재시도 예산을 다 쓰고 증상만 보이는 오류로 실패하는 것을 지켜볼 필요 없이 즉시 알 수 있습니다. REGION_UNSUPPORTED는 영구적입니다. 해당 엔진은 요청한 국가를 서빙할 수 없습니다.

{
  "success": false,
  "error": {
    "code": "REGION_UNSUPPORTED",
    "message": "CHATGPT cannot be served for country='CN': no proxy vendor has exit supply in CN. This is a permanent capability gap, not a transient one — retrying will not help. GOOGLE and AIMODE are unaffected by exit-IP limits and remain available for this country.",
    "details": { "taskType": "CHATGPT", "country": "CN", "cause": "no_proxy_route", "retryable": false },
    "timestamp": "2026-07-09T04:12:00.000Z"
  }
}

서빙할 수 없는 조합 표를 참고하세요. REGION_UNAVAILABLE는 일시적입니다. 경로는 있지만 지금은 서빙할 수 있는 것이 없습니다. GET /capacity로 지역별로 현재 서빙 가능한 범위를 확인하세요.

배치 실패는 항목별입니다

형식이 올바른 배치는 안의 태스크가 모두 실패해도 항상 200을 반환합니다. HTTP 상태는 요청을, results[].success는 각 태스크를 설명합니다.

{
  "success": true,
  "summary": { "total": 3, "succeeded": 2, "failed": 1 },
  "results": [
    { "success": true,  "index": 0, "task": { "...": "..." } },
    { "success": false, "index": 1, "error": { "code": "REGION_UNAVAILABLE", "message": "..." } },
    { "success": true,  "index": 2, "task": { "...": "..." } }
  ]
}

요청 전체가 잘못된 경우(JSON이 아님, 배열이 아님, 비어 있음, 500개 초과, 8 MB 초과, 인증 실패)에만 배치 자체가 4xx를 반환합니다.

배치 항목은 REGION_UNAVAILABLE 또는 ENQUEUE_ERROR로 실패할 수 있는데, 둘 다 이 API가 구현하는 비동기 태스크 계약의 항목별 오류 enum에는 없습니다. 둘은 대체가 아니라 추가이며, VALIDATION_ERROR와 RESOURCE_ALREADY_EXISTS는 그대로입니다.

태스크 수준 실패

큐에 들어간 뒤에 실패한 태스크는 HTTP 오류를 전혀 만들지 않습니다. 종료 상태로 알게 됩니다.

{
  "success": true,
  "task": { "id": "8f2c1e40-...", "status": "FAILED", "...": "..." },
  "credits": { "creditsToCharge": 0, "creditsCharged": 0 },
  "error": "ENGINE_TIMEOUT: The engine did not answer before the task deadline."
}

형태 차이에 주의하세요. 이 최상위 error는 요청 수준 오류가 쓰는 {code, message, timestamp} 객체가 아니라 문자열입니다. 코드로 시작하고 그 코드마다 정해진 문장이 뒤따르므로 코드로 분기하세요. ENGINE_TIMEOUT, ENGINE_NO_RESULT, ENGINE_FAILED가 있고, 제시간에 처리 용량이 나지 않으면 NO_IP_AVAILABLE이나 NO_ACCOUNT_AVAILABLE입니다(보통 나중에 다시 시도하면 됩니다). BAD_PAYLOAD와 PAGE_UNAVAILABLE(익명으로 읽을 수 없는 네이버 페이지)은 무엇을 바꿔야 하는지 알려주는 메시지를 그대로 둡니다. 같은 태스크는 task.status === "FAILED"인 webhook도 전달합니다.

시작하기

핵심 개념

엔진

Source Influence

Prompt Research

GEO 모니터링

마이그레이션

오류

코드

지역 거부

배치 실패는 항목별입니다

태스크 수준 실패

​코드

​지역 거부

​배치 실패는 항목별입니다

​태스크 수준 실패

코드

지역 거부

배치 실패는 항목별입니다

태스크 수준 실패