오류
공개 API는 안정적인 HTTP 상태 코드와 기계가 읽을 수 있는 오류 봉투를 사용합니다. SDK 호출자는 2xx가 아닌 모든 응답에 대해 타입이 지정된 FabHubApiError를 받습니다.
오류 형태
{
"error": {
"code": "SCOPE_REQUIRED",
"message": "This credential is missing the items:write scope",
"request_id": "req_8f3a...",
"details": {}
}
}
request_id는 대부분의 응답에 포함됩니다 - 지원 요청 시 이를 인용하세요. details는 검증 오류에 대해 존재합니다. message가 아니라 안정적인 error.code로 분기하세요.
상태 코드
| 상태 | 의미 |
|---|---|
400 | 잘못된 요청 또는 검증 오류 |
401 | 누락되었거나, 유효하지 않거나, 만료되었거나, 취소된 자격 증명 |
403 | 스코프 누락, 플랜 게이트 또는 IP 허용 목록 거부 |
404 | 리소스를 찾을 수 없음 |
409 | 멱등성 충돌(다른 페이로드로 키 재사용) |
429 | 속도 제한 초과 |
500 | 서버 오류 |
오류 코드
BAD_REQUEST,UNAUTHORIZED,FORBIDDEN,NOT_FOUND,CONFLICT,RATE_LIMITED,INTERNAL_ERRORSCOPE_REQUIRED- 자격 증명에 필요한 스코프가 없음PLAN_REQUIRED- 테넌트의 플랜에 이 기능이 포함되어 있지 않음OBJECT_ACCESS_DENIED- 참조된 객체가 테넌트 외부에 있음TENANT_DISABLED,ENDPOINT_DISABLED- 킬 스위치MCP_CONFIRMATION_REQUIRED- 쓰기/파괴적 MCP 도구에 명시적인 확인이 필요함
예시
{ "error": { "code": "NOT_FOUND", "message": "Item not found", "request_id": "req_1a..." } }
{ "error": { "code": "RATE_LIMITED", "message": "Rate limit exceeded; retry after the window resets", "request_id": "req_2b..." } }
클라이언트 지침
401과 403은 재시도 가능한 실패가 아니라 구성 또는 권한 문제로 취급하세요. 429는 속도 제한 윈도가 재설정된 후에만 재시도 가능한 것으로 취급하세요. 쓰기에 멱등성 키를 사용하여 전송 실패를 안전하게 재시도할 수 있도록 하세요. 멱등성과 속도 제한을 참조하세요.