Errors & FAQ

HTTP 상태 코드

코드는 표면마다 다릅니다

Core.Today는 두 개의 독립된 표면을 제공하고, 둘은 서로 다른 코드 집합을 씁니다. 아래 표의 “표면” 열이 어느 쪽이 그 코드를 내는지 알려줍니다.

• • AI API — /v1/predictions, /v1/files, /v1/databases 등.
• • LLM gateway — OpenAI·Anthropic·Gemini 호환 LLM 경로.

에러 응답 형태

에러 응답은 아래 봉투를 따릅니다. detail은 문자열일 수도, { code, message, … } 객체일 수도 있습니다 (422는 검증 항목 배열). 레이트리밋·용량 거절·쿼터 초과처럼 트래픽이 많은 경로는 대부분 객체 형태라 String(detail)을 하면 [object Object]가 찍힙니다. 표시는 error.message를, 분기는 error.code를 쓰세요 — message 문구는 예고 없이 다듬어집니다.

{
  "detail": {
    "code": "customer_wallet_insufficient",
    "message": "End-customer 'acme-01' budget exhausted. Required: 120. Top up ..."
  },
  "error": {
    "type": "api_error",
    "code": "customer_wallet_insufficient",
    "message": "End-customer 'acme-01' budget exhausted. ...",
    "request_id": "3f2a9c1e-...",
    "wallet_remaining": 30.0,
    "topup_required": 90.0
  },
  "request_id": "3f2a9c1e-..."
}

• • request_id는 모든 응답의 X-Request-Id 헤더에도 실립니다. 문의 시 이 값을 함께 보내주시면 해당 요청의 서버 로그를 바로 찾을 수 있습니다.
• • 코드별로 error에 추가 필드가 붙습니다 (예: 402의 topup_required, 동시성 429의 group/limit, 사용량 429의 reset_at, model_retired의 replacement).
• • 재시도 가능한 응답에는 Retry-After 헤더가 붙습니다. 공식 SDK는 이 값을 자동으로 존중합니다.

에러 코드 레퍼런스 (동기 응답)

요청이 즉시 거절될 때 error.code로 전달되는 값입니다. “표면” 열이 어느 제품이 그 코드를 내는지, “원인 주체” 열이 누가 고쳐야 하는 문제인지 알려줍니다 — Core.Today로 표시된 항목은 요청 측 잘못이 아니며 키·잔액을 건드릴 필요가 없습니다.

에러 코드 레퍼런스 (예측 실패)

POST /predictions는 즉시 job_id를 반환하므로, 실제 실패 사유는 GET /predictions/{job_id} 응답의 error_code로 전달됩니다 (status는 failed). 이 표는 AI API 전용입니다.

실패한 예측의 크레딧은 자동 환불됩니다. 다만 credits_used가 0인지로 환불 여부를 판정하지는 마세요 — 오래된 레코드와 만료 후 폴백 조회는 이 값이 null(“알 수 없음”)입니다. 실제 청구 내역은 사용량·청구 API를 기준으로 확인하세요.

Rate Limits

API 키별 기본 한도 — 초과 시 api_key_rate_limited(AI API) 또는 rate_limited (LLM 게이트웨이)

팀 단위로 상향 조정할 수 있습니다. 리셀러 워크스페이스의 키는 여러 end-customer 트래픽이 합산 통과하므로 훨씬 높은 상한이 적용되고, 실질 게이트는 아래 end-customer별 한도가 맡습니다.

리셀러 end-customer별 한도 (X-Customer-Id 단위)

요청 속도(customer_rate_limited), 카테고리별 동시 실행 수(customer_concurrency_exceeded, 기본 이미지 10·비디오 5), 분당 LLM 토큰(customer_token_rate_limited)을 지갑별로 설정할 수 있습니다. 현재 사용 현황은 GET /reseller/customers/{id}/concurrency로 확인하세요. 스토리지 용량도 같은 단위로 제한할 수 있습니다 — 초과 시 403 customer_storage_quota_exceeded(지갑 storage_quota > 워크스페이스 default_customer_storage_* 순으로 적용).

IP 기반 제한은 2026-05-05에 폐지됐습니다 — 인증된 요청에는 중복이었고, 사무실·모바일 NAT처럼 IP를 공유하는 정상 사용자를 오탐했기 때문입니다. 429를 받았다면 IP가 아니라 위 한도 중 하나이며, error.code가 어느 쪽인지 알려줍니다.

자주 묻는 질문