API 멱등성
n8n v2.47요약
퍼블릭 API POST 요청에 Idempotency-Key 헤더를 보내면, 재시도 시 요청을 다시 실행하지 않고 처음 성공한 응답을 반환합니다. n8n API의 멱등성은 n8n 2.45.0부터 사용할 수 있습니다. 무료 체험판에서는 사용할 수 없습니다.
퍼블릭 API POST 요청에 Idempotency-Key 헤더를 보내면, 재시도 시 요청을 다시 실행하지 않고 처음 성공한 응답을 반환합니다.
기능 사용 가능 여부
n8n API의 멱등성은 n8n 2.45.0부터 사용할 수 있습니다.
- n8n Cloud: Starter, Pro, Enterprise
- 셀프 호스팅: 모든 에디션
무료 체험판에서는 사용할 수 없습니다.
이 헤더는 선택 사항입니다. 헤더를 생략하면 각 POST 요청이 평소처럼 실행됩니다.
멱등성 키 보내기#
첫 번째 POST 요청에 Idempotency-Key 헤더를 설정하고, 재시도할 때 동일한 헤더를 다시 보냅니다. 서로 다른 요청마다 새 키를 사용합니다. 버전 4 UUID를 사용하면 안전합니다. n8n은 이 형식을 요구하지 않습니다.
값은 공백 없이 문자, 숫자, 기호로 이루어진 1자에서 128자 사이의 표시 가능한 ASCII 문자여야 합니다. n8n은 키 앞뒤의 공백을 무시합니다. 빈 값이나 공백만 있는 값은 헤더를 생략한 것과 같습니다.
curl -X POST \
'https://<your-instance>/api/v1/workflows' \
-H 'accept: application/json' \
-H 'X-N8N-API-KEY: <your-api-key>' \
-H 'Idempotency-Key: <idempotency-key>' \
-H 'Content-Type: application/json' \
-d '<workflow-json>'
<workflow-json>을 워크플로 본문으로 바꿉니다. API 키 생성 방법은 인증을 참조하세요.
키가 너무 길거나 공백 또는 허용되지 않는 다른 문자가 포함되어 있으면 400을 반환하며 리소스를 생성하지 않습니다. 메시지는 Idempotency-Key must be 1 to 128 visible ASCII characters.입니다.
키를 사용하는 요청#
n8n은 워크플로 생성이나 POST /api/v1/executions/<execution-id>/retry 호출처럼 무언가를 생성하거나 작업을 시작하는 POST 요청에서 이 헤더를 사용합니다. 엔드포인트 레퍼런스에는 이 헤더를 허용하는 각 POST에 헤더가 표시되어 있습니다.
n8n은 GET, PUT, PATCH, DELETE 요청에서는 이 헤더를 무시합니다.
n8n이 응답을 보관하는 기간#
n8n은 키를 보낸 시점부터 12시간 동안 처음 성공한 응답을 보관합니다. 이 기간 안에 재시도하면 해당 응답을 반환하며 POST를 다시 실행하지 않습니다.
12시간이 지나면 같은 키로 POST가 다시 실행되며 중복이 생성될 수 있습니다. 다음 작업에는 새 키를 보내세요.
키는 하나의 API 키가 아니라 사용자에게 속합니다. 같은 사용자의 API 키 두 개는 저장된 응답을 공유합니다. 다른 사용자가 보낸 같은 키는 별도의 요청으로 처리됩니다.
동일한 요청 재시도#
동일한 경로, 쿼리 문자열, 본문을 JSON 필드 순서와 공백까지 포함해 같은 키와 함께 다시 보냅니다. 일치하면 첫 번째 응답과 같은 상태 코드와 JSON 본문을 반환합니다.
파일을 반환하는 POST는 적용 대상이 아닙니다. 이 요청을 재시도하면 요청이 다시 실행됩니다.
같은 키, 다른 요청#
경로, 쿼리 문자열 또는 본문이 다르면 n8n은 422를 반환하며 POST를 실행하지 않습니다.
{
"message": "This Idempotency-Key was already used with a different request."
}
변경된 요청에는 새 키를 보내세요. 처음 생성된 리소스는 그대로 유지됩니다.
요청이 아직 진행 중인 경우#
첫 번째 요청이 아직 끝나지 않았으면 n8n은 409를 반환합니다.
{
"message": "A request with this Idempotency-Key is already in progress."
}
잠시 기다린 다음 같은 키와 같은 요청을 다시 보냅니다. 하나의 키로 동시에 두 요청을 보내도 리소스가 두 개 생성되지 않습니다. 한 요청이 작업을 완료하고, 다른 요청은 409를 받거나 첫 번째 요청이 이미 끝났다면 첫 번째 응답을 받습니다.
요청이 실패하는 경우#
POST가 실패하면 n8n은 해당 응답을 보관하지 않습니다. 같은 키와 같은 요청으로 재시도하면 POST가 다시 실행됩니다.
본문이 유효하지 않아 첫 번째 POST가 400을 반환했다면 본문을 수정한 다음 같은 키를 다시 보내세요.
멱등성 키의 한계#
멱등성 헤더는 /api/v1의 퍼블릭 API 엔드포인트에만 적용됩니다.