Unif API Docs오류
UnifAPI가 에이전트와 HTTP 클라이언트에 반환하는 모든 오류, 그 의미, 복구 방법.
오류는 어떤 공개 데이터 작업을 호출했는지와 관계없이 항상 동일한 엔벨로프로 반환됩니다:
{
"error": {
"type": "rate_limited",
"message": "Workspace rate limit exceeded.",
"request_id": "unif_5471f8cfa3814204a280b73df8c93167"
}
}error.type은 닫힌 어휘(아래 표 참고)에서 옵니다 — 안정적이고, 기계가 읽을 수 있으며, 에이전트와 클라이언트가 분기 처리하기에 안전합니다.error.message는 사람을 위한 것이며 예고 없이 변경될 수 있습니다.error.request_id는 UnifAPI 추적 id입니다. 지원 요청 시 포함하세요.error.issues는type = validation_error일 때만 존재합니다 — 원시 Zod issue 목록입니다.
HTTP 상태는 type을 그대로 반영합니다 — 클라이언트는 원하는 신호를 선택할 수 있습니다.
레퍼런스
| 상태 | type | 발생 시점 | 복구 |
|---|---|---|---|
| 400 | validation_error | 게이트웨이 측 검증에 요청이 실패했습니다(잘못된 쿼리, 누락된 body 필드). | error.issues를 검사하세요. 요청을 수정하세요. |
| 400 | invalid_id | 제공된 id가 구문적으로는 유효하지만 공개 소스에서 수락되지 않았습니다. | 실제 id를 사용하세요. |
| 401 | unauthorized | OAuth 또는 API 키 자격 증명이 누락, 형식 오류, 폐기 또는 비활성화되었습니다. | 다시 인증하거나 키를 교체하세요. |
| 404 | not_found | 리소스(video, user, room, ...)가 존재하지 않거나, 삭제되었거나, 비공개입니다. | id를 확인하세요. 일부 리소스는 비공개이며 설계상 404를 반환합니다. |
| 429 | rate_limited | 워크스페이스 또는 소스 속도 제한을 초과했습니다. | Retry-After를 준수하세요. 속도 제한을 참고하세요. |
| 500 | internal_error | UnifAPI 자체가 실패했습니다(처리되지 않은 예외). | 재시도해도 안전합니다. 지속되면 request_id를 보고하세요. |
| 500 | response_shape_error | 소스 데이터가 더 이상 게시된 스키마와 일치하지 않습니다. | request_id를 보고하세요 — drift는 버그입니다. |
| 502 | upstream_error | 공개 데이터 소스가 UnifAPI가 복구할 수 없는 오류를 반환했습니다. | error.message를 검사하세요. |
| 503 | upstream_unavailable | 공개 데이터 소스가 타임아웃되었거나 접근할 수 없습니다. | 지수 백오프로 재시도하세요. |
위 표는 현재 오류 어휘에 대한 공개 계약입니다.
검증 오류의 구조
validation_error의 경우, issues 배열은 원시 Zod issue 목록을 담아 에이전트나 호출자가 오류를 필드에 다시 매핑할 수 있게 합니다:
{
"error": {
"type": "validation_error",
"message": "Request validation failed.",
"issues": [
{
"code": "too_big",
"maximum": 50,
"type": "number",
"inclusive": true,
"path": ["limit"],
"message": "Number must be less than or equal to 50"
}
]
}
}항상 request_id를 로깅하세요
모든 오류 응답은 UnifAPI가 첨부할 수 있을 때 request_id를 담습니다. 이를 로깅하고 지원 요청에 포함하세요. 실패한 Skill 실행이나 HTTP 호출을 디버깅하는 가장 빠른 방법입니다.