시작하기
오류 및 재시도
표준 JSON 오류 엔벨로프를 파싱하고 재시도해도 안전한 시점을 판단합니다.
오류 엔벨로프
JSON API 실패는 최상위 error 객체 하나를 사용하며, 사람이 읽을 수 있는 message, 숫자 HTTP status, 선택 사항인 안정적인 code가 들어 있습니다. OpenAPI 명세는 예상된 실패와 예상하지 못한 실패 모두에 이 스키마를 참조합니다.
{
"error": {
"code": "invalid_request",
"message": "A verified From domain is required",
"status": 403
}
}클라이언트 오류
재시도하기 전에 400 입력 오류를 바로잡으세요. 401 이후에는 유효하지 않은 자격 증명을 교체하거나 폐기하세요. 402는 유료 권한이 필요하다는 뜻이고, 403은 정책 또는 권한의 경계를 나타내며, 404는 테넌트 범위에 없는 리소스이고, 409는 상태 또는 멱등성 충돌이며, 413은 첨부 파일 한도를 초과한 경우이고, 422는 유효성 검사 또는 발송 제외에 해당합니다.
재시도 판단
인증, 유효성 검사, 발송 제외, 충돌로 인한 실패는 자동으로 재시도하지 마세요. 423은 해당 From ID가 일시 중지되었다는 뜻입니다. 그 발송 흐름을 중단하고 수신자를 바로잡은 뒤, 롤링 지표가 정상으로 돌아온 후에만 재시도하세요. 일시적인 429, 502, 503 응답은 상한이 있는 지수 백오프와 지터를 적용해 재시도할 수 있습니다. 하나의 논리적 발송을 재시도할 때는 같은 Idempotency-Key와 동일한 JSON 페이로드를 유지하세요.
지원 문의 시 필요한 정보
요청 시각, 경로, HTTP 상태, SendHQ 리소스 ID, 비밀이 아닌 오류 필드를 기록하세요. 지원 요청에는 API 키, 세션 쿠키, 메시지 본문, 수신자 목록을 절대 포함하지 마세요.