API 오류 응답
Foundry API 오류는 보통 HTTP 4xx 또는 5xx 상태와 JSON 본문으로 반환됩니다. 본문에는 오류 코드, 구체적인 오류 이름, 발생 건 ID와 추가 매개변수가 있습니다. 발생 건 ID는 Palantir 지원팀이 특정 오류를 조사할 때 사용할 수 있습니다.
다음은 존재하지 않거나 접근할 수 없는 직원 객체를 조회했을 때의 형식을 보여 주는 예시입니다.
{
"errorCode": "NOT_FOUND",
"errorName": "ObjectNotFound",
"errorInstanceId": "00813215-0844-4716-be7b-a3fe0fce9e42",
"parameters": {
"objectType": "employee",
"primaryKey": {"id": 10000}
}
}
| 필드 | 의미 |
|---|---|
errorCode | 오류의 공통 분류 |
errorName | 구체적인 오류 종류 |
errorInstanceId | 개별 오류 발생 건 식별자 |
parameters | 문제를 설명하는 리소스 ID, 필드나 상태 등의 추가 정보 |
오류 코드와 HTTP 상태는 각각 확인합니다. 아래 표에는 개별 오류에 지정된 조합을 표시합니다. NOT_FOUND 오류는 리소스가 없을 때뿐 아니라 토큰으로 접근할 수 없을 때도 발생할 수 있습니다.
온톨로지 오류
| 오류 이름 | 오류 코드 | HTTP | 원인과 대응 | 추가 매개변수 |
|---|---|---|---|---|
ActionEditedPropertiesNotFound | INVALID_ARGUMENT | 400 | 액션이 객체 유형에 없는 속성을 편집하려고 했습니다. | parameters |
ActionParameterObjectTypeNotFound | NOT_FOUND | 400 | 매개변수가 참조하는 객체 유형을 찾을 수 없거나 토큰이 접근할 수 없습니다. | parameterId |
ActionParameterObjectNotFound | NOT_FOUND | 400 | 매개변수의 객체 참조 또는 기본 객체 값을 찾을 수 없거나 토큰이 접근할 수 없습니다. | parameterId |
ActionTypeNotFound | NOT_FOUND | 404 | 요청한 액션을 찾을 수 없거나 토큰이 접근할 수 없습니다. | actionType |
ActionValidationFailed | INVALID_ARGUMENT | 400 | 액션 매개변수 검증에 실패했습니다. validateAction으로 상세 정보를 확인합니다. | actionType |
AggregationGroupCountExceededLimit | INVALID_ARGUMENT | 400 | 집계 그룹 수가 한도를 넘었습니다. maxGroupCount, 더 큰 구간 또는 필터로 결과 수를 줄입니다. | groupsCount, groupsLimit |
ApplyActionFailed | INVALID_ARGUMENT | 400 | 액션을 온톨로지에 적용하지 못했습니다. | 없음 |
AttachmentNotFound | NOT_FOUND | 404 | 첨부 파일을 찾을 수 없거나 토큰이 접근할 수 없습니다. | attachmentRid |
AttachmentSizeExceededLimit | INVALID_ARGUMENT | 400 | 첨부 파일이 최대 200 MB를 넘었습니다. | fileSizeBytes, fileLimitBytes |
CompositePrimaryKeyNotSupported | INVALID_ARGUMENT | 400 | 여러 속성으로 구성된 복합 기본 키를 지원하지 않습니다. 지원이 필요하면 Palantir에 문의합니다. | objectType, primaryKey |
DuplicateOrderBy | INVALID_ARGUMENT | 400 | 정렬 조건에 같은 속성을 중복 지정했습니다. | properties |
FunctionEncounteredUserFacingError | INVALID_ARGUMENT | 400 | 함수가 오류를 발생시켜 실행에 실패했습니다. | functionRid, functionVersion, message |
FunctionInvalidInput | INVALID_ARGUMENT | 400 | 실행한 함수의 입력이 유효하지 않습니다. | functionRid, functionVersion |
FunctionExecutionTimedOut | INVALID_ARGUMENT | 400 | 함수 실행이 시간 제한을 넘었습니다. | functionRid, functionVersion |
InvalidContentLength | INVALID_ARGUMENT | 400 | 업로드에 필요한 Content-Length 헤더가 없거나 잘못되었습니다. | 없음 |
InvalidContentType | INVALID_ARGUMENT | 400 | 요청 내용과 filename으로 콘텐츠 유형을 판단할 수 없습니다. 두 값의 호환성을 확인합니다. | 없음 |
InvalidDurationGroupByValue | INVALID_ARGUMENT | 400 | 기간별 그룹화 값이 유효하지 않습니다. 일보다 큰 단위는 값이 1이어야 하며 날짜 속성에는 일보다 작은 단위의 필터를 사용할 수 없습니다. | 없음 |
InvalidDurationGroupByPropertyType | INVALID_ARGUMENT | 400 | 해당 속성은 기간별 그룹화 연산을 지원하지 않습니다. | property, objectType, propertyBaseType |
InvalidFields | INVALID_ARGUMENT | 400 | 필드가 필요한 패턴에 맞지 않습니다. 예를 들어 이 필드 경로 규칙에서는 객체 속성 id를 properties.id로 표현합니다. | properties |
InvalidGroupId | INVALID_ARGUMENT | 400 | 그룹 ID가 UUID가 아닙니다. | groupId |
InvalidParameterValue | INVALID_ARGUMENT | 400 | 매개변수 값이 유효하지 않습니다. | parameterId, parameterBaseType, parameterValue |
InvalidPropertyFiltersCombination | INVALID_ARGUMENT | 400 | 지정한 속성 필터를 함께 사용할 수 없습니다. | property, propertyFilters |
InvalidPropertyType | INVALID_ARGUMENT | 400 | 속성 자료형이 기대한 유형과 다릅니다. | property, propertyBaseType |
InvalidPropertyValue | INVALID_ARGUMENT | 400 | 속성값이 유효하지 않습니다. | property, propertyBaseType, propertyValue |
InvalidSortOrder | INVALID_ARGUMENT | 400 | 정렬 방향이 잘못되었습니다. asc 또는 desc를 사용하며 생략 시 asc입니다. | invalidSortOrder |
InvalidSortType | INVALID_ARGUMENT | 400 | 정렬 절의 유형이 잘못되었습니다. properties 또는 p를 사용합니다. | invalidSortType |
InvalidUserId | INVALID_ARGUMENT | 400 | 사용자 ID가 UUID가 아닙니다. | userId |
LinkAlreadyExists | CONFLICT | 400 | 생성하려는 링크가 이미 존재합니다. | 없음 |
LinkedObjectNotFound | NOT_FOUND | 404 | 연결 객체를 찾을 수 없거나 토큰이 접근할 수 없습니다. | linkType, linkedObjectType, linkedObjectPrimaryKey |
LinkTypeNotFound | NOT_FOUND | 404 | 링크 유형을 찾을 수 없거나 토큰이 접근할 수 없습니다. | objectType, linkType |
MalformedPropertyFilters | INVALID_ARGUMENT | 400 | 요청한 필터 중 하나 이상이 올바른 형식이 아닙니다. | malformedPropertyFilter |
MultiplePropertyValuesNotSupported | INVALID_ARGUMENT | 400 | 여러 값을 지원하지 않는 속성 필터에 복수 값을 넣었습니다. 한 값만 지정합니다. | property, propertyFilters |
ObjectNotFound | NOT_FOUND | 404 | 객체를 찾을 수 없거나 토큰이 접근할 수 없습니다. | objectType, primaryKey |
ObjectsExceededLimit | INVALID_ARGUMENT | 400 | 결과가 더 있지만 해당 요청의 전체 조회 한도를 넘었습니다. 10,000개 제한이 적용되는 작업에서 발생하며 저장소별 적용 범위는 개별 엔드포인트를 따릅니다. | 없음 |
ObjectTypeNotFound | NOT_FOUND | 404 | 객체 유형을 찾을 수 없거나 토큰이 접근할 수 없습니다. | objectType |
ObjectTypeNotSynced | CONFLICT | 409 | 객체 유형이 온톨로지에 동기화되지 않았습니다. Ontology Manager에서 다시 인덱싱합니다. | objectType |
OntologyEditsExceededLimit | INVALID_ARGUMENT | 400 | 온톨로지 편집 수가 한도를 넘었습니다. 액션이 너무 많은 객체를 바꾸는 경우 등이 해당합니다. | editsCount, editsLimit |
OntologyNotFound | NOT_FOUND | 404 | 온톨로지를 찾을 수 없거나 토큰이 접근할 수 없습니다. | ontologyRid |
OntologySyncing | CONFLICT | 409 | Ontology Manager에서 바꾼 객체 유형을 적용 중입니다. 몇 초 뒤 다시 시도합니다. | objectType |
ParametersNotFound | INVALID_ARGUMENT | 400 | 액션이 인식하지 못하는 매개변수 ID가 있습니다. configuredParameterIds의 유효한 ID를 확인합니다. | actionType, unknownParameterIds, configuredParameterIds |
ParameterTypeNotSupported | INVALID_ARGUMENT | 400 | 이 매개변수 유형을 지원하지 않습니다. 지원이 필요하면 Palantir에 문의합니다. | parameterId, parameterBaseType |
PropertiesNotFound | NOT_FOUND | 404 | 요청한 속성이 객체 유형에 없습니다. | objectType, properties |
PropertiesNotSearchable | INVALID_ARGUMENT | 400 | 속성 검색이 활성화되지 않았습니다. Ontology Manager에서 해당 속성을 Searchable로 지정합니다. | properties |
PropertiesNotSortable | INVALID_ARGUMENT | 400 | 요청한 속성으로 정렬할 수 없습니다. Ontology Manager에서 해당 속성을 Sortable로 지정합니다. | properties |
PropertyApiNameNotFound | INVALID_ARGUMENT | 400 | 기본 키처럼 API 이름이 필요한 속성에 이름이 없습니다. Ontology Manager에서 설정합니다. | propertyId, propertyBaseType |
PropertyBaseTypeNotSupported | INVALID_ARGUMENT | 400 | 해당 속성 기본 유형을 지원하지 않습니다. 지원이 필요하면 Palantir에 문의합니다. | objectType, property, propertyBaseType |
PropertyFiltersNotSupported | INVALID_ARGUMENT | 400 | 요청한 속성 필터 중 하나 이상을 지원하지 않습니다. | property, propertyFilters |
QueryEncounteredUserFacingError | CONFLICT | 409 | 사용자로 인해 발생한 오류로 작성한 Query가 실패했습니다. message는 사용자에게 표시하기 위한 내용입니다. | functionRid, functionVersion, message |
QueryRuntimeError | INVALID_ARGUMENT | 400 | Query 실행 중 런타임 오류가 발생했습니다. | functionRid, functionVersion, message, stacktrace, parameters |
QueryTimeExceededLimit | INVALID_ARGUMENT | 400 | Query 실행 시간 한도를 넘었습니다. | functionRid, functionVersion |
QueryMemoryExceededLimit | TIMEOUT | 400 | Query 실행 메모리 한도를 넘었습니다. | functionRid, functionVersion |
ViewObjectPermissionDenied | PERMISSION_DENIED | 403 | 객체 유형의 기반 데이터 소스를 볼 권한이 없습니다. 기반 데이터 소스가 구성되어 있고 접근 가능한지 확인합니다. | objectType |
데이터셋 오류
| 오류 이름 | 오류 코드 | HTTP | 원인과 대응 | 추가 매개변수 |
|---|---|---|---|---|
AbortTransactionPermissionDenied | PERMISSION_DENIED | 403 | 해당 데이터셋의 트랜잭션을 중단할 권한이 없습니다. | datasetRid, transactionRid |
BranchAlreadyExists | CONFLICT | 409 | 같은 이름의 브랜치가 이미 존재합니다. | datasetRid, branchId |
BranchNotFound | NOT_FOUND | 404 | 브랜치를 찾을 수 없거나 토큰이 접근할 수 없습니다. | datasetRid, branchId |
ColumnTypesNotSupported | INVALID_ARGUMENT | 400 | 지원하지 않는 열 자료형이 있습니다. | datasetRid |
CommitTransactionPermissionDenied | PERMISSION_DENIED | 403 | 트랜잭션을 커밋할 권한이 없습니다. | datasetRid, transactionRid |
CreateBranchPermissionDenied | PERMISSION_DENIED | 403 | 데이터셋에 브랜치를 만들 권한이 없습니다. | datasetRid, branchId |
CreateDatasetPermissionDenied | PERMISSION_DENIED | 403 | 폴더에 데이터셋을 만들 권한이 없습니다. | parentFolderRid, name |
CreateTransactionPermissionDenied | PERMISSION_DENIED | 403 | 데이터셋에 트랜잭션을 만들 권한이 없습니다. | datasetRid, branchId |
DatasetNotFound | NOT_FOUND | 404 | 데이터셋을 찾을 수 없거나 토큰이 접근할 수 없습니다. | datasetRid |
DeleteBranchPermissionDenied | PERMISSION_DENIED | 403 | 데이터셋의 브랜치를 삭제할 권한이 없습니다. | datasetRid, branchId |
FileAlreadyExists | NOT_FOUND | 404 | 데이터셋과 트랜잭션에 해당 파일 경로가 이미 있습니다. | datasetRid, transactionRid, path |
FileNotFoundOnBranch | NOT_FOUND | 404 | 지정 브랜치에서 파일을 찾을 수 없거나 토큰이 접근할 수 없습니다. | datasetRid, branchId, path |
FileNotFoundOnTransactionRange | NOT_FOUND | 404 | 지정 트랜잭션 범위에서 파일을 찾을 수 없거나 토큰이 접근할 수 없습니다. | datasetRid, endTransactionRid, path |
InvalidBranchId | INVALID_ARGUMENT | 400 | 브랜치 이름이 비어 있거나 RID 또는 UUID처럼 보입니다. 사용할 수 있는 이름으로 바꿉니다. | branchId |
InvalidTransactionType | INVALID_ARGUMENT | 400 | 트랜잭션 유형이 유효하지 않습니다. SNAPSHOT, UPDATE, APPEND, DELETE 중 사용합니다. | datasetRid, transactionRid, transactionType |
OpenTransactionAlreadyExists | CONFLICT | 409 | 해당 데이터셋 브랜치에 열린 트랜잭션이 있습니다. 브랜치마다 한 번에 하나만 열 수 있습니다. | datasetRid, branchId |
ReadTablePermissionDenied | PERMISSION_DENIED | 403 | 데이터셋을 표로 읽을 권한이 없습니다. | datasetRid |
SchemaNotFound | NOT_FOUND | 404 | 데이터셋과 브랜치의 스키마를 찾을 수 없거나 토큰이 접근할 수 없습니다. | datasetRid, branchId |
TransactionNotCommitted | INVALID_ARGUMENT | 400 | 지정 트랜잭션이 커밋되지 않았습니다. | datasetRid, transactionRid, transactionStatus |
TransactionNotFound | NOT_FOUND | 404 | 데이터셋에서 트랜잭션을 찾을 수 없거나 토큰이 접근할 수 없습니다. | datasetRid, transactionRid |
TransactionNotOpen | INVALID_ARGUMENT | 400 | 지정 트랜잭션이 열린 상태가 아닙니다. | datasetRid, transactionRid, transactionStatus |
UploadFilePermissionDenied | PERMISSION_DENIED | 403 | 해당 데이터셋과 트랜잭션에 파일을 업로드할 권한이 없습니다. | datasetRid, transactionRid, path |
파일시스템과 작업 오류
| 오류 이름 | 오류 코드 | HTTP | 원인 | 추가 매개변수 |
|---|---|---|---|---|
FolderNotFound | NOT_FOUND | 404 | 폴더를 찾을 수 없거나 토큰이 접근할 수 없습니다. | folderRid |
ResourceNameAlreadyExists | CONFLICT | 409 | 같은 폴더의 다른 리소스가 해당 이름을 사용하고 있습니다. | resourceName, parentFolderRid |
OperationNotFound | NOT_FOUND | 404 | 작업을 찾을 수 없거나 사용자가 접근할 수 없습니다. | id |
공통 오류
모든 Foundry API에서 다음 오류가 발생할 수 있습니다.
| 오류 이름 | 오류 코드 | HTTP | 원인과 대응 |
|---|---|---|---|
ApiFeaturePreviewUsageOnly | INVALID_ARGUMENT | 400 | 비운영 프리뷰 전용 엔드포인트입니다. 사용하려면 preview=true를 추가합니다. |
ApiUsageDenied | PERMISSION_DENIED | 403 | 사용자 또는 토큰이 해당 API를 사용할 권한이 없습니다. |
Conjure:InvalidArgument | INVALID_ARGUMENT | 400 | 요청 인수 중 하나 이상이 유효하지 않습니다. |
Conjure:UnprocessableEntity | INVALID_ARGUMENT | 422 | 요청 인수 중 하나 이상이 유효하지 않습니다. |
Conjure:UnsupportedMediaType | INVALID_ARGUMENT | 415 | Content-type이 잘못되었습니다. application/json을 사용합니다. |
Default:Internal | INTERNAL | 500 | 서비스 내부 오류입니다. 다시 요청해도 계속되면 지원 티켓을 제출합니다. |
Default:InvalidArgument | INVALID_ARGUMENT | 400 | 요청 인수 중 하나 이상이 유효하지 않습니다. |
Default:PermissionDenied | PERMISSION_DENIED | 403 | 요청 처리에 필요한 정보에 접근할 권한이 없습니다. |
Default:Unauthorized | UNAUTHORIZED | 401 | 인증 토큰 헤더가 유효하지 않습니다. |
InvalidPageSize | INVALID_ARGUMENT | 400 | 페이지 크기가 0 이하입니다. 양수를 사용합니다. |
InvalidPageToken | INVALID_ARGUMENT | 400 | 페이지 토큰으로 다음 결과를 가져올 수 없습니다. |
InvalidParameterCombination | INVALID_ARGUMENT | 400 | 각 매개변수는 유효하지만 지정한 조합으로는 사용할 수 없습니다. |
MissingCredentials | UNAUTHORIZED | 401 | 필수 인증 토큰 헤더가 없습니다. |
오류 본문이 없는 응답
일부 오류에는 이름이나 JSON 본문이 없습니다. 이때는 HTTP 상태로 원인을 확인합니다.
| HTTP | 의미와 대응 |
|---|---|
| 404 | 요청한 엔드포인트가 없습니다. URL을 확인합니다. |
| 414 | URL이 너무 깁니다. 쿼리 매개변수를 줄이거나 해당 엔드포인트가 제공하는 대체 요청 방식을 확인합니다. |
| 429 | 요청이 너무 많습니다. 잠시 뒤 재시도하고 요청 빈도를 줄입니다. |
| 431 | URL 또는 HTTP 헤더가 너무 깁니다. 헤더나 쿼리 매개변수를 줄이거나 다른 지원 방식을 사용합니다. |
| 503 | 서비스를 사용할 수 없습니다. 나중에 다시 시도합니다. |
예외적인 상황에는 여기에 없는 오류도 반환될 수 있습니다. HTTP 상태의 의미와 오류 발생 건 ID를 확인하고, 해결이 어려우면 지원 티켓에 정보를 포함합니다.