속도 제한 및 API 오류
Telemetry 엔드포인트는 표준 HTTP 상태 코드를 사용합니다. 클라이언트는 재시도하기 전에 요청 결함과 임시 서비스 또는 용량 조건을 구별해야 합니다.
계획별 할당량 및 현재 한도는 변경될 수 있습니다. 제품 및 결제 설정에 표시된 한도를 계정의 정보 소스로 간주하세요. 문서화되지 않은 글로벌 요청 속도를 하드 코딩하지 마십시오.
응답 클래스
| 상태 | 의미 | 클라이언트 작업 |
|---|---|---|
200 또는 202 |
작업이 성공했거나 비동기 작업이 수락되었습니다. | 응답 본문을 읽고 계속하세요. |
400 |
잘못된 JSON, SQL, 테이블 이름, 필드 유형 또는 요청 형태 | 요청을 수정하세요. 변경하지 않고 다시 시도하지 마세요 |
401 |
API 키가 누락되었거나 잘못되었거나 취소되었습니다. | 자격 증명 교체 |
403 |
키에 필요한 범위가 없습니다. | 올바른 범위의 키를 사용하세요. |
404 |
요청한 테이블, 작업, 대시보드, 알림 또는 경로가 존재하지 않습니다. | 식별자와 팀을 확인하세요 |
409 또는 422 |
요청이 현재 상태와 충돌하거나 적용할 수 없습니다. | 오류를 확인하고 동작을 변경하세요. |
429 |
현재 요청 비율 또는 할당량이 초과되었습니다. | 존재하는 경우 Retry-After를 존중하고 물러납니다. |
5xx |
Telemetry가 유효한 요청을 완료할 수 없습니다. | 백오프를 사용하여 제한된 횟수만큼 재시도 |
오류 본문에는 보다 구체적인 컨텍스트가 포함될 수 있습니다. 상태, 엔드포인트 이름, 요청 ID 및 안전 오류 카테고리를 기록합니다. 단지 요청이 실패했다는 이유만으로 API 키나 원래 이벤트 페이로드를 기록하지 마세요.
안전하게 다시 시도하세요
429, 502, 503 및 504 응답에 지터가 포함된 지수 백오프를 사용합니다. 원격 분석 중단으로 인해 애플리케이션 작업자가 소진되지 않도록 시도와 총 경과 시간을 모두 제한합니다.
delay = min(max_delay, base_delay * 2^attempt) + random_jitter
요청을 수정하지 않고 400 응답을 재시도하지 마세요. 잘못된 스키마 또는 SQL 쿼리를 반복적으로 전송하면 성공 경로를 생성하지 않고 로드가 생성됩니다.
이벤트 정체성 유지
수집을 재시도할 때 논리적 이벤트에 대해 안정적인 event_id를 재사용하세요. 이를 통해 중복 전달을 측정할 수 있으며 멱등성 소비자가 재시도를 인식할 수 있습니다. 모든 네트워크 시도에 대한 새로운 식별자는 하나의 결과를 구별할 수 없는 여러 비즈니스 이벤트로 바꿉니다.
재시도 동작을 감사하려면 중복 이벤트 ID 레시피를 사용하세요.
바운드 실패 영향
원격 분석이 중요한 경로에 있는지 결정합니다. 대부분의 제품 계측의 경우 이미 성공한 고객 응답을 변경하지 않고 안전한 진단 채널을 통해 일시적인 수집 실패를 보고해야 합니다. 규정 준수 또는 청구 워크플로의 경우 내구성 있는 대기열이 적합할 수 있습니다.
대규모 결과 집합의 경우 대화형 요청을 반복적으로 재시도하는 대신 비동기 쿼리 API를 사용하세요. 범위 규칙은 API 키 및 인증을 참조하세요.