· reAPI Team
OpenRouter PDF 오류: 파서가 요청 제한에 걸렸을 때
파일 가져오기, 파서 제한, 모델 실패를 구분해 OpenRouter PDF 오류를 진단하세요. 처리 경로, 재시도, 재사용 가능한 파일 주석을 비교합니다.

모델을 바꾸고 같은 PDF를 다시 보내도 파싱 엔진의 요청 제한 오류가 또 반환됩니다. 모델은 바뀌었지만 문서는 여전히 먼저 같은 파서를 거칠 수 있습니다.
OpenRouter는 PDF를 파일을 기본 지원하는 모델로 직접 보낼 수도 있고, 해당 지원이 없는 모델로 내용을 전달하기 전에 PDF를 파싱할 수도 있습니다. 문서에 따르면 기본 설정은 가능한 경우 기본 처리를 우선하며, 그렇지 않으면 Mistral OCR을 사용합니다.[1] 따라서 서로 다른 두 모델 이름을 사용해도 앞선 파싱 단계는 그대로일 수 있습니다. 같은 오류에 다시 시도하기 전에 해당 처리 경로를 확인하세요.
이 PDF가 어디서 멈췄는지 확인하기
상태, 요청 ID, 선택한 모델, 엔드포인트, 엔진이 포함된 전체 응답을 저장하세요. 엔진 설정이 기본값인지 명시적으로 지정된 값인지 기록하고, 지정되지 않은 경로를 의도적으로 선택한 것처럼 설명하지 마세요.
입력 형식은 API에 따라 다릅니다. Responses는 file_url 또는 file_data가 포함된 input_file 콘텐츠 항목을 사용합니다. Chat Completions는 file 콘텐츠 파트를 사용합니다.[1] 엔드포인트 사이에서 요청을 복사하면서 형식을 맞추지 않으면 파서 용량이 문제가 되기 전에 실패할 수 있습니다.
다음으로 파일 전달을 확인하세요. 로그인된 브라우저에서 PDF가 열리더라도 서비스가 같은 로그인 없이 동일한 URL을 가져올 수 있다는 뜻은 아닙니다. OpenRouter 문서는 직접 가져오기에는 공개 URL을, 로컬 또는 비공개 문서에는 base64 입력을 사용하도록 안내합니다.[1] 적절하고 허용된 방법을 사용하세요. 기밀 문서를 공개하는 것은 문제 해결에 필요하지 않습니다.
오류가 파싱 엔진을 언급한다면 그 표현을 그대로 보존하세요. 파일을 가져올 수 없다는 오류라면 먼저 전달 방식을 수정하세요. 파싱은 완료됐지만 추론에 실패했다면 전체 작업을 다시 시도하기 전에 파싱된 내용을 보존하세요. 이 사례들은 모두 애플리케이션에서 일반적인 “PDF 실패” 메시지로 나타날 수 있지만, 필요한 후속 작업은 서로 다릅니다.
HTTP 상태뿐 아니라 본문이나 스트림도 읽으세요. OpenRouter 문서는 헤더가 이미 전송된 뒤에 오류가 도착할 수 있으며, 성공 상태로 시작된 응답 내부에서도 실패가 발생할 수 있다고 설명합니다.[2] 200만 기록하는 HTTP 로거는 애플리케이션이 처리해야 할 실패를 놓칠 수 있습니다.
모델 전환은 관련 경로도 바꿀 때만 도움이 됩니다
PDF 가이드에는 native, mistral-ocr, cloudflare-ai의 세 엔진이 나옵니다. 기본 처리는 파일을 지원 모델로 전달합니다. Mistral OCR은 문서 내용을 추출하고 Cloudflare AI는 PDF를 Markdown으로 변환합니다.[1]
서술형 텍스트, 재무 표, 차트가 들어 있는 가상의 보고서를 생각해 보면, 선택은 질문에 따라야 합니다. 텍스트 변환만으로도 서술 내용을 요약하기에는 충분할 수 있습니다. 차트 레이블에 관한 질문이라면 해당 레이블이 보존되어 모델이 사용할 수 있어야 합니다. 답변을 반환하는 경로라고 해서 그 질문에 필요한 증거까지 반드시 보존한 것은 아닙니다.
같은 OCR 경로가 필요한 두 모델 사이에서 전환하면 파서 오류가 계속될 수 있습니다. 기본 PDF 지원 모델을 선택하고 해당 경로를 사용하면 문서 처리 경로도 바뀝니다. 모델 계열 이름만으로 지원 여부를 추정하지 말고 정확한 모델의 입력 제한과 적합성을 확인하세요.
이전 예시에는 pdf-text가 사용될 수 있습니다. OpenRouter의 현재 가이드에서는 이 엔진을 사용 중단 예정으로 표시하고 cloudflare-ai로 리디렉션합니다.[1] 레이블을 업데이트하면 의도한 경로를 더 명확히 할 수 있지만, 그것만으로 변환 품질이나 처리 용량이 향상됐다는 뜻은 아닙니다.
BYOK를 사용해도 OCR 단계의 요금은 없어지지 않습니다. OpenRouter는 이 작업에 자체 Mistral 키를 사용하며 추론에 개인 제공업체 키를 사용하더라도 OCR 요금은 OpenRouter 계정에 청구된다고 설명합니다.[1] 다른 모델 자격 증명을 사용한다는 사실만으로 별도의 파서 할당량을 확보했다는 증거가 되지는 않습니다.
다시 파싱하기 전에 이미 결과가 있는지 확인하기
유용한 복구 사례는 파서가 작업을 마친 뒤에 시작됩니다. 가상의 보고서가 파싱됐지만 시도한 모든 추론 제공업체가 완성 결과를 생성하지 못했다고 가정해 보세요. Chat Completions에서 OpenRouter는 오류에 파싱된 파일 주석이 error.metadata.file_annotations 아래 남아 있을 수 있다고 설명합니다.[1]
즉 실패한 응답에도 이미 완료된 유용한 작업이 들어 있을 수 있습니다. 응답을 버리기 전에 일반 assistant 메시지 주석과 문서에 안내된 오류 위치를 모두 읽으세요.
| 응답 내 위치 | 확인할 내용 |
|---|---|
| Chat Completions assistant 메시지 | 파싱된 내용과 파일 해시가 포함된 재사용 가능한 file 주석 |
Chat Completions error.metadata.file_annotations | 파싱은 성공했지만 추론 제공업체가 실패한 뒤에도 포함되는 동일한 형태의 파싱 파일 주석 |
| Responses 출력 주석 | 파싱을 건너뛰기 위해 반환할 수 없는 file_citation 참조 |
이 구분은 OpenRouter의 PDF 가이드에서 확인할 수 있습니다.[1] 문서를 가리키는 인용은 재사용 가능한 파싱 문서와 같은 객체가 아닙니다.
재사용 가능한 주석 전체를 설명 대상 문서와 함께 보관한 다음, 후속 허용 요청에는 가이드의 Chat Completions 재사용 형식을 따르세요. 파싱을 건너뛸 수 있는 것은 주석의 파싱된 내용과 해시 덕분입니다. 파일 이름이나 답변의 인용만 복사해서는 해당 내용이 제공되지 않습니다.
성공 응답과 오류 응답에서 주석을 모두 수집한다면 문서에 지정된 중복 제거 식별자는 file.hash입니다. 애플리케이션에서 원본 문서와의 연결을 보존하세요. 보고서 예시에서 다른 분기 보고서의 주석을 실수로 연결하면 잘못된 증거에 바탕을 둔 그럴듯한 답변이 나올 수 있습니다.
이 경로는 파싱 경로에 적용됩니다. 기본 처리는 PDF를 직접 전달하므로 이러한 파서 주석을 생성하지 않습니다. 또한 파싱이 완료되지 않은 시도는 주석 재사용으로 복구할 수 없습니다.[1] 사용할 수 있는 파싱 결과가 없다면 주석을 만들어내지 말고 문서를 대기 상태로 유지한 채 실패한 단계를 처리하세요.
저장된 주석에는 추출된 텍스트와 이미지가 포함될 수 있습니다. 무해한 진단 메타데이터가 아니라 적절한 접근 및 보존 관리가 필요한 문서 콘텐츠의 복사본으로 취급하세요. 파일 보존 가이드는 이러한 복사본을 추적하는 방법을 다룹니다. 범용 오류 로그에 기밀 주석 전체를 넣지 마세요.
저장된 파싱 결과와 문서 버전을 함께 보관하세요. 파일 이름은 유지한 채 누군가 보고서를 교체했다면 어제 추출한 내용으로 오늘 파일의 내용을 확인할 수 없습니다. 재사용하기 전에 저장된 내용이 질문 대상 버전에 속하는지 확인하세요. 익숙한 파일 이름만으로는 충분히 일치한다고 볼 수 없습니다.
전체 배치를 다시 시작하지 않고 문서 미루기
응답에 스로틀링이 표시되면 재시도 안내를 확인하세요. OpenRouter는 관련 요청 제한 또는 가용성 응답에 Retry-After가 포함될 수 있다고 설명합니다.[2] HTTP 헤더 값은 초 단위 지연 또는 HTTP 날짜일 수 있으며, 숫자 값은 밀리초가 아닙니다.[3]
유효한 대기 시간이 반환되면 다음 허용 시도 전에 해당 시간만큼 기다리세요. 문서 작업의 마감 시간을 넘긴다면 보이지 않는 재시도 루프를 계속 실행하지 말고 작업을 명시적으로 미루세요. 사용할 만한 안내가 없다면 제공업체 문서의 처리 방식을 따르고 시도 횟수와 총 경과 시간 모두에 상한을 두세요.
SDK나 워크플로가 이미 재시도하는지 확인하세요. 재시도하는 헬퍼 바깥에 루프를 추가하면 실제 시도 횟수가 바깥 카운터에 표시된 횟수보다 많아질 수 있습니다. 대기 시간을 포함해 문서별 시도를 하나의 기록으로 관리하여 배치가 계속 제약된 단계로 되돌아가지 않게 하세요.
배치에서는 문서별 진행 상태를 보존하세요. 보고서 9개가 이미 완료됐고 열 번째가 미뤄졌다면 10개 모두를 다시 시작하면서 유용한 차이를 없애게 됩니다. 완료된 보고서, 파싱은 됐지만 답변이 없는 보고서, 파싱을 기다리는 문서를 서로 다른 상태로 유지하세요. 이는 애플리케이션 스케줄링 권장 사항이지 OpenRouter가 배치를 그런 방식으로 관리한다는 주장은 아닙니다.
제어할 수 있는 작업자를 조정하세요. 각 작업자가 적은 수의 요청만 보내더라도 여러 작업자의 요청이 같은 경로로 모이면 큰 요청 급증이 생길 수 있습니다. 공유 큐를 사용하면 전체 부하를 파악할 수 있습니다. 추가 키나 계정으로 OpenRouter의 전역 관리 용량을 늘릴 수 있다는 내용은 문서에 없습니다.[4]
대체 경로가 무엇을 보존했는지 확인하기
보고서의 답변을 받아들이기 전에 선택한 경로가 제공한 정보를 살펴보세요. 연속된 텍스트 요약과 모든 차트의 비교에는 서로 다른 요구사항이 있습니다. 첫 번째는 성공하더라도 두 번째에는 중요한 이미지가 빠져 있을 수 있습니다.
Mistral OCR의 경우 OpenRouter 문서는 PDF당 최대 8개의 이미지를 요청하고 각 다운스트림 요청에 최대 8개까지 전달한다고 설명합니다. 초과 이미지는 삭제되지만 추출된 텍스트는 보존됩니다. 다운스트림 모델이 이미지를 받을 수 없다면 파싱된 텍스트만 전달됩니다.[1]
따라서 요청이 성공했다는 이유만으로 빠진 이미지에 관한 답변을 신뢰할 수는 없습니다. 관련 시각적 증거가 포함됐는지 확인하세요. 직접 텍스트를 추출해 추론에 보내기로 했다면 표 구조, 페이지 매핑, 스캔 자료나 다이어그램에서 손실된 정보가 있는지 살펴보세요. 이는 자체 추출 워크플로이며 다른 이름의 OpenRouter 엔진이 아닙니다.
대기 시간과 이미 청구된 작업을 구분하기
PDF 요청이 느리면 경과 시간에는 파일 가져오기, 파싱, 모델 처리, 재시도 사이의 대기가 포함될 수 있습니다. 추적 기록에서 실제로 확인되는 구간을 사용하세요. 추론 모델을 바꿔도 파서를 기다리거나 자체 큐에서 대기한 시간이 사라진다고 단정할 수 없습니다.
이 모든 경로에 적용할 수 있는 유용한 단일 “OpenRouter 지연 시간” 수치는 없습니다. 소요 시간을 측정할 때는 문서 특성, 엔진, 모델, 동시성을 함께 기록하세요. 이 가이드는 지연 시간 벤치마크를 실행하지 않았으며 예상 완료 시간도 제시하지 않습니다. 클라이언트가 기다림을 멈춘 시각은 각 원격 단계의 측정값과 다릅니다.
요금도 수행된 작업을 따릅니다. 기본 입력은 모델 입력 가격으로 청구됩니다. OCR에는 별도 요금이 있습니다. Cloudflare 변환은 무료 처리로 문서화되어 있지만 이후 모델 추론까지 무료라는 뜻은 아닙니다.[1]
OpenRouter의 제로 완성 보호는 조건을 충족하는 모델 토큰 요금과 이미 수행된 보조 작업을 구분합니다. 실제 작업과 실패 사례에 따라 이후 답변이 실패해도 파싱이나 OCR 요금이 청구될 수 있습니다.[5] 전체 시도가 무료라고 판단하거나 자체 추정에서 두 번 청구하기 전에 요금 내역을 확인하세요.
보고서에서 마지막으로 완료된 단계로 돌아가세요. 파일을 가져오지 못했다면 입력을 수정하세요. 파싱이 미뤄졌다면 큐에서 그 위치를 유지하세요. 재사용 가능한 파싱 내용이 있다면 다음 적절한 추론 시도를 위해 보존하세요. 이러한 복구 방식은 바뀌지 않은 파서를 우회하리라 기대하며 다른 모델 이름을 선택하는 대신 실제 문서 상태를 따릅니다.
문서 입력용으로 reAPI를 검토한다면
reAPI에서 문서 입력은 각 모델 문서에 설명된 기본 형식을 따릅니다. PDF를 포함한 미디어는 공개 HTTP(S) URL로 보내야 하며, base64와 data: URI는 허용되지 않습니다.[6] 지원 여부는 모델마다 다릅니다. 예를 들어 Claude Sonnet 5.5 참조 문서에는 PDF 입력이 아직 검증되지 않았다고 적혀 있습니다. PDF 워크플로를 옮기기 전에 해당 모델 페이지를 확인하고, 어떤 서비스가 파일을 처리하든 위의 속도 제한 대응은 유지하세요.
참고 자료
- OpenRouter, “PDF Inputs,” 공식 문서. 2026년 11월 16일 전체 확인; 엔진, API 형식, OCR 이미지 및 주석 섹션.
- OpenRouter, “Errors and Debugging,” 공식 문서, 오류 봉투, 오류 코드 및 Retry-After 섹션. 2026년 11월 15일 검색; 관련 섹션은 11월 16일 검토.
- MDN, Retry-After header. 2026년 11월 16일 확인.
- OpenRouter, “Limits,” 공식 문서, 소개 및 요청 제한 처리 섹션. 2026년 11월 16일 확인.
- OpenRouter, “Zero Completion Insurance,” 공식 문서. 2026년 11월 15일 검색; 모델 토큰과 보조 요금의 차이를 확인하기 위해 11월 16일 정책 전체 검토.
- reAPI. Claude Sonnet 5.5 API 참조: 입력 형식. 2026년 11월 17일 검토. Claude Sonnet 5.5.