가이드

멱등성

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

작동 방식

클라이언트에서 생성한 고유 문자열을 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는 범용 레이블이 아닌 정확히 동일한 요청을 재시도하기 위한 것입니다. 이미 사용한 키를 다른 요청 매개변수와 함께 재사용하면, API는 이전 응답을 자동으로 재생하지 않으며 어떤 요청을 의도했는지 추측하지 않습니다. 대신 400 idempotency_key_reused 오류를 반환합니다. 동일한 종류의 작업을 대상으로 하더라도 요청이 실제로 다른 경우에는 새 키를 생성하십시오.

예시: 재생된 응답

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

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

기록되는 내용

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

📮 contact email: [email protected]