범위 및 오류

모든 공개 API 작업에는 명시적인 범위 하나가 필요합니다. 유효한 자격 증명에 해당 범위가 없으면 403 insufficient_scope를 반환하며 권한을 자동으로 넓히지 않습니다.

범위 레퍼런스#

보고 작업에는 읽기 범위를 사용하세요. 연동이 실제로 변경 작업을 수행할 때만 쓰기 범위를 추가합니다. 예를 들어 리드 내보내기는 일반적으로 sites:read와 leads:read만 필요하며 sites:write나 agents:write는 필요하지 않습니다.

범위 오류#

{
  "error": {
    "code": "insufficient_scope",
    "message": "The API key does not grant the required scope.",
    "details": { "required": ["sites:write"] },
    "request_id": "6c0b2f2e-..."
  }
}

설정 → 개발자 → 수정에서 키에 누락된 범위를 추가하거나, 대체 키를 만들고 서버 시크릿을 업데이트하세요. 수정하면 키의 이름과 범위가 그 자리에서 바뀌며 만료일과 토큰은 그대로 유지됩니다. OAuth로 발급된 키는 수정할 수 없으므로, 부여된 권한을 바꾸려면 애플리케이션을 다시 연결하세요.

오류 응답 형식#

모든 API 오류는 같은 최상위 구조를 사용합니다.

type ApiError = {
  error: {
    code: string;
    message: string;
    details?: unknown;
    request_id: string;
  };
};

영문 message가 아니라 error.code로 분기하세요. 메시지는 버전 변경 없이 개선될 수 있습니다. 작업 이름, 상태, 재시도 횟수와 함께 error.request_id 및 x-request-id 응답 헤더를 기록하되 Authorization 헤더나 요청 시크릿은 기록하지 마세요.

상태 및 코드 레퍼런스#

자격 증명 소유자의 계정 밖에 있는 리소스는 다른 테넌트의 ID 존재 여부를 숨기기 위해 404를 반환할 수 있습니다.

검증 상세 정보#

필드 검증은 자신의 폼 컨트롤 옆에 표시할 수 있는 경로를 반환합니다.

{
  "error": {
    "code": "invalid_request",
    "message": "Request validation failed.",
    "details": [
      { "path": "content.headline", "message": "String must contain at least 1 character(s)" }
    ],
    "request_id": "6c0b2f2e-..."
  }
}

변경 요청 본문은 JSON 객체여야 합니다. 배열, 빈 본문, 폼 데이터, 텍스트 콘텐츠 유형으로 보낸 JSON은 거부됩니다.

재시도 판단#

• 429는 Retry-After 초 뒤에 재시도합니다.
• 500은 안전한 읽기 또는 같은 Idempotency-Key로 보호된 쓰기만 재시도합니다.
• 처리 중인 멱등성 409는 Retry-After: 2 헤더 뒤에 재시도합니다.
• 503 outcome_unknown은 무작정 재시도하지 않습니다. 먼저 리소스를 확인하고, 변경이 일어나지 않았음을 확인한 뒤에만 새 멱등성 키를 사용합니다.
• 400, 401, 403, 404, 413 또는 상태 충돌은 원인이 바뀌기 전까지 재시도하지 않습니다.

백오프 동작은 요청 한도, 작업별 필수 범위는 API 레퍼런스를 참고하세요.