Errors

모든 에러 코드, 원인, 복구 방법.

Last updated: 2026-04-23

Veacon API 는 의미가 명확한 HTTP status code + machine-readable error.code 를 반환합니다. 클라이언트는 error.code 만으로 분기하면 됩니다.

공통 에러 응답 포맷

json

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or revoked API Key"
  },
  "_meta": { "service": "veacon", "api_version": "v1" }
}

error.code — 고정 상수 (문자열). 이것만 변화 감지하면 됨.
error.message — 사람이 읽는 설명. 변경 가능.
추가 필드 — 일부 에러는 retry_after_seconds, current_usage, resets_at, hint 등 동반.

에러 매트릭스

HTTP	Code	원인	복구
400	`INVALID_PARAMS`	쿼리 파라미터 누락, 형식 오류	응답의 `error.errors` 배열 확인 후 요청 수정
401	`UNAUTHORIZED`	`X-API-Key` 또는 `veacon_session` 쿠키 없음/잘못됨	키 재발급 또는 재로그인
402	`QUOTA_EXCEEDED`	월 호출 쿼터 소진	`resets_at` 까지 대기 또는 플랜 업그레이드
404	`NOT_FOUND`	해당 region × category × period 조합에 데이터 없음	/markets/dimensions 로 가능 조합 조회
405	`METHOD_NOT_ALLOWED`	지원하지 않는 HTTP method	GET 만 지원
429	`RATE_LIMITED`	분당 호출 한도 초과	`Retry-After` 초만큼 대기 후 재시도
500	`QUERY_FAILED`	DB 쿼리 오류 (서버측)	재시도 or hello@veacon.io 문의
500	`INTERNAL`	기타 서버 오류	재시도 or 문의

상세 샘플

400 INVALID_PARAMS

json

{
  "error": {
    "code": "INVALID_PARAMS",
    "message": "'period' must be 'YYYY-MM' format (e.g., '2026-01')",
    "errors": ["'period' must be 'YYYY-MM' format (e.g., '2026-01')"]
  },
  "_meta": { "service": "veacon", "api_version": "v1" }
}

402 QUOTA_EXCEEDED

json

{
  "error": {
    "code": "QUOTA_EXCEEDED",
    "message": "Monthly quota of 10000 reached. Upgrade at https://veacon.io/pricing",
    "current_usage": 10000,
    "resets_at": "2026-05-01T00:00:00.000Z"
  },
  "_meta": { "service": "veacon", "api_version": "v1" }
}

응답 헤더에도 동일 정보:

X-Quota-Limit: 10000
X-Quota-Used: 10000
X-Quota-Resets-At: 2026-05-01T00:00:00.000Z

429 RATE_LIMITED

json

{
  "error": {
    "code": "RATE_LIMITED",
    "message": "Rate limit exceeded",
    "retry_after_seconds": 35
  },
  "_meta": { "service": "veacon", "api_version": "v1" }
}

응답 헤더: Retry-After: 35

404 NOT_FOUND

json

{
  "error": {
    "code": "NOT_FOUND",
    "message": "No data for given parameters",
    "hint": "Call /api/v1/markets/dimensions to list available values"
  },
  "_meta": { "service": "veacon", "api_version": "v1" }
}

권장 재시도 정책

401, 402, 400, 404, 405 — 재시도 금지 (요청 자체가 잘못)
429 — Retry-After 초 후 1회 재시도. 연속 실패 시 exponential backoff (1s, 2s, 4s, ...)
500 — 최대 3회 exponential backoff (1s, 2s, 4s)

클라이언트 예제

Python

python

import time
import requests

def pulse(region, category, period, key):
    for attempt in range(4):
        r = requests.get(
            "https://veacon.io/api/v1/markets/pulse",
            headers={"X-API-Key": key},
            params={"region": region, "category": category, "period": period},
            timeout=10,
        )
        if r.status_code == 200:
            return r.json()["data"]
        if r.status_code == 429:
            time.sleep(int(r.headers.get("Retry-After", "1")))
            continue
        if r.status_code >= 500 and attempt < 3:
            time.sleep(2 ** attempt)
            continue
        # 400/401/402/404/405 → do not retry
        r.raise_for_status()
    raise RuntimeError("exceeded max retries")

이상 동작 신고

위 매트릭스에 없는 에러가 발생하거나 error.code 가 변경된다면 hello@veacon.io 로 응답 전체와 발생 시각을 보내주세요. 24시간 내 응답.