Error

오류 응답 구조

모든 엔드포인트는 통합된 envelope 로 오류를 반환합니다.

{
  "success": false,
  "error": {
    "code":    "INVALID_URL",
    "status":  400,
    "message": "The provided URL is not valid",
    "details": null
  }
}

필드

• success (boolean): 오류 시 항상 false
• error.code (string): 기계 가독 오류 코드 — 오류 코드 참조
• error.status (number): HTTP 상태 코드 (응답 상태와 동일; 원시 상태에 접근할 수 없을 때 유용)
• error.message (string): 사람이 읽기 좋은 오류 설명
• error.details (object | null): 오류의 구조화된 컨텍스트 — 예: INVALID_PARAMETER에서 { field: message } 형식의 필드별 검증 오류 반환; 해당 없을 때 null

TypeScript 타입

type ErrorResponse = {
  success: false;
  error: {
    code: string;       // machine-readable, e.g. "INVALID_URL"
    status: number;     // HTTP status code
    message: string;    // human-readable
    details: Record<string, unknown> | null;
  };
};

안정된 계약: 위 4개 error.* 필드는 보장됩니다. 향후 추가 필드는 하위 호환을 유지하므로 클라이언트는 알 수 없는 필드를 안전하게 무시할 수 있습니다.