가이드

멱등성

네트워크 호출은 실패하고 타임아웃이 발생합니다. 크레딧을 소모하거나 리소스를 생성하는 요청에서 이러한 상황이 발생했을 때 단순히 재시도하면 크레딧이 두 번 사용될 수 있습니다. Idempotency-Key 헤더가 이 문제를 해결합니다. 재시도 시 동일한 키를 보내면 원래 호출과 완전히 동일한 응답을 반환받으며, 작업이 다시 실행되지 않습니다.

작동 방식

클라이언트에서 생성한 고유 문자열(UUID 권장)을 Idempotency-Key 헤더에 담아 지원되는 요청에 추가하세요.

curl -X POST https://imagetotable.ai/api/v1/batches/260716-4K9P/process \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 7f3e9a2c-9b41-4e6a-8c3d-2f1a5b6c7d8e" \
  -d '{"fields": [{"name": "invoice_number"}, {"name": "total_amount"}]}'

키는 24시간 동안 (계정, 키 값, 엔드포인트)별로 저장됩니다. 동일한 요청(동일한 엔드포인트, 동일한 키)이 해당 시간 내에 다시 도착하면 원래 응답(동일한 상태 코드, 동일한 본문)이 재생되며, 작업 자체는 두 번 실행되지 않습니다. 즉, 동일한 키로 재시도된 process 호출은 크레딧을 두 번 차감하지 않으며, 동일한 키로 재시도된 documents 업로드는 두 번째 문서를 생성하지 않습니다.

Idempotency-Key 헤더가 없는 요청은 이전과 동일하게 작동합니다. 아무것도 저장되지 않으며 재생되지 않습니다. 이 헤더는 전적으로 선택 사항입니다.

지원하는 엔드포인트

크레딧을 사용하거나 리소스를 생성하는 엔드포인트만 Idempotency-Key를 허용합니다. 읽기 전용 GET 요청에는 이점이 없습니다. 읽기 반복은 항상 안전하기 때문입니다:

  • POST /documents (문서 생성)
  • POST /batches/{batch_name}/process (처리 시작, 크레딧 차감)
  • POST /documents/{document_id}/bbox (유료 bbox 주석 단계 실행)

다른 매개변수로 키 재사용

Idempotency-Key는 범용 레이블이 아닌 정확히 동일한 요청을 재시도하기 위한 것입니다. 이미 사용한 키를 다른 요청 매개변수(다른 batch_name, 다른 요청 본문)와 함께 재사용하면, API는 이전 응답을 자동으로 재생하지 않으며(다른 요청에 대해 잘못된 동작임) 어떤 요청을 의도했는지 추측하지 않습니다. 대신 400 idempotency_key_reused 오류를 반환합니다. 동일한 종류의 작업을 대상으로 하더라도 요청이 실제로 다른 경우에는 새 키를 생성하십시오.

예시: 재생된 응답

아래 두 번째 호출은 이미 성공한 호출과 동일한 키로 이루어졌으며, 첫 번째 호출과 동일한 본문과 상태 코드를 반환합니다. 크레딧이 다시 차감되지는 않습니다:

{
  "batch_name": "260716-4K9P",
  "queued": 2,
  "quality": "fast",
  "webhook_registered": false
}

기록되는 내용

재생을 위해 저장되는 것은 성공(2xx) 응답뿐입니다. 원래 호출이 실패한 경우(유효성 검사 오류, 크레딧 부족 등 2xx가 아닌 모든 경우) 아무것도 기록되지 않으며, 동일한 키로 재시도하면 작업을 새로 시도합니다. 이는 의도된 설계입니다. 오류가 발생한 상황에서는 키가 24시간 후 만료될 때까지 동일한 실패가 재생되는 것이 아니라, 재시도가 실제로 다시 시도되기를 원하기 때문입니다.

📮 contact email: [email protected]