API 요청이 성공하면 API는 응답 본문에서 요청된 데이터와 함께 200 OK 상태 코드를 반환합니다. 오류가 발생하면 API는 HTTP 상태 코드에 매핑되고 오류 정보가 포함된 응답 본문과 함께 Google API로 정의된 표준 오류 코드 중 하나를 반환합니다. 오류가 발생하면 JSON 응답 본문의 message 및 status 필드에서 디버깅에 도움이 되는 구체적인 세부정보를 검사합니다.
오류 형식
요청으로 인해 오류가 발생하면 API는 적절한 HTTP 상태 코드와 JSON 응답 본문을 반환합니다. 오류 응답에는 다음 구조의 error 객체가 포함됩니다.
{
"error": {
"code": 403,
"message": "User does not have sufficient permissions for this property.",
"status": "PERMISSION_DENIED"
}
}
error 객체에는 다음 필드가 포함됩니다.
| 필드 | 설명 |
|---|---|
| 코드 | HTTP 상태 코드(예: 400, 401, 403, 429, 500)입니다. |
| message | 오류에 대한 짧은 설명입니다. |
| 상태 | 표준 오류 코드입니다(예: INVALID_ARGUMENT, UNAUTHENTICATED, PERMISSION_DENIED, RESOURCE_EXHAUSTED, INTERNAL). |
일반적인 오류
다음 표에는 API에서 반환되는 일반적인 오류가 나와 있습니다.
| HTTP 상태 코드 | 표준 코드 | 이유 | 설명 |
|---|---|---|---|
| 400 | INVALID_ARGUMENT |
잘못된 요청 | 요청의 형식이 잘못되었습니다. 잘못된 기간 또는 형식이 잘못된 필터와 같은 매개변수가 누락되었거나 잘못되어 발생할 수 있습니다. |
| 401 | UNAUTHENTICATED |
사용자 인증 정보가 잘못됨 | 요청에 대상 리소스와 관련된 올바른 사용자 인증 정보가 없습니다. OAuth 2.0 액세스 토큰이 누락되었거나, 잘못되었거나, 만료된 경우에 발생할 수 있습니다. OAuth 2.0으로 인증의 안내에 따라 유효한 토큰을 가져옵니다. |
| 403 | PERMISSION_DENIED |
권한 없음 | 인증된 사용자에게 요청된 Google 애널리틱스 속성에 대한 액세스 권한이 없습니다. |
| 429 | RESOURCE_EXHAUSTED |
할당량 초과 | API 할당량 한도에 도달하여 요청이 거부되었습니다. 자세한 내용은 Data API 한도 및 할당량을 참고하세요. 프로젝트별 또는 속성별 한도를 초과했을 수 있습니다. |
| 500 | INTERNAL |
내부 서버 오류 | 예기치 않은 서버 오류가 발생했습니다. 일시적인 문제인 경우가 많습니다. 지수 백오프를 사용하여 요청을 다시 시도하는 것이 좋습니다. 서버 오류 할당량을 초과하지 않으려면 재시도 한도를 사용하여 지수 백오프를 구현하는 것이 중요합니다. |
| 503 | UNAVAILABLE |
서비스를 사용할 수 없음 | 서비스를 일시적으로 사용할 수 없습니다. 일시적인 문제인 경우가 많습니다. 지수 백오프를 사용하여 요청을 다시 시도하는 것이 좋습니다. 서버 오류 할당량을 초과하지 않으려면 재시도 한도를 사용하여 지수 백오프를 구현하는 것이 중요합니다. |