> ## Documentation Index > Fetch the complete documentation index at: https://docurise.io/docs/llms.txt > Use this file to discover all available pages before exploring further. # 에러 > 에러 응답 형식, 모든 에러 코드와 각 코드에 대한 대응 방법 `/api/preview/*`의 에러는 엔드포인트와 관계없이 하나의 JSON 형식을 사용합니다. ```json theme={null} { "error": { "code": "REVISION_CONFLICT", "message": "The document changed since you read it: ...", "retryable": false } } ``` | 필드 | 항상 포함 | 의미 | | - | - | - | | `code` | 예 | `UPPER_SNAKE_CASE` 형식의 안정적인 기계 판독용 코드입니다. 이 값을 기준으로 분기하세요. | | `message` | 예 | 로그와 디버깅용 설명입니다. 언제든 문구가 바뀔 수 있으니 파싱하지 마세요. | | `retryable` | 예 | 동일한 요청을 다시 보내면 성공할 수 있으면 `true`입니다. `false`이면 먼저 무언가를 바꿔야 합니다. | | `retryAfterSeconds` | 아니요 | 재시도 전에 기다릴 시간(초)입니다. 구체적인 힌트가 없으면 생략됩니다(`null`로 오지 않습니다). | | `details` | 아니요 | 일부 코드에만 붙는 기계 판독용 상세 정보입니다(아래 표에 표시). 다른 코드에서는 생략됩니다. | 에러는 `code`로 처리하고, 모르는 코드는 HTTP 상태와 `retryable` 값으로 판단하세요. 프리뷰 기간에는 새 코드가 추가될 수 있습니다. JSON 본문이 없는 응답도 있습니다: 존재하지 않는 경로(`404`), 라우트가 지원하지 않는 메서드(`405`, 예: Instagram 규칙에 `DELETE`), 그리고 드물게 인증이나 속도 제한 처리가 예기치 않게 실패한 경우의 `5xx`입니다. 본문을 파싱할 수 없는 `5xx`는 재시도 가능한 것으로 취급하세요. ## 재시도 * **`retryable: true`**: 잠시 기다린 뒤 같은 요청을 다시 보내세요. `retryAfterSeconds`(`429`에서는 `Retry-After` 헤더)가 있으면 그 값을 따르고, 없으면 1\~2초부터 시작해 지터를 넣어 지수적으로 간격을 늘리세요. 재시도는 5회 정도로 제한하고, 짧은 간격으로 반복해서 보내지 말고, `retryAfterSeconds`가 `0`이어도 최소 1초는 기다리세요. * **`retryable: false`**: 같은 요청은 같은 이유로 다시 실패합니다. 아래 표에 따라 입력을 고치거나, 리소스를 다시 조회하거나, 대시보드에서 사람이 조치하도록 알리세요. * **`Idempotency-Key`를 쓰는 생성 요청** (`POST /api/preview/documents`, `POST /api/preview/instagram/rules`, `POST /api/preview/segments`): 생성 요청이 직접 재시도 가능하다고 보고한 실패(예: 재시도 가능한 `NOTION_FETCH_FAILED`, `INSTAGRAM_UNAVAILABLE`)는 키를 해제하므로 **같은** 키와 본문으로 재시도하세요. 재시도할 수 없는 실패는 키에 저장되므로, 같은 키와 본문을 다시 보내면 같은 에러가 다시 반환됩니다. 요청을 고친 뒤에는 **새** 키로 보내세요(기존 키를 다른 본문으로 재사용하면 `409 IDEMPOTENCY_KEY_CONFLICT`입니다). * **`500 INTERNAL_ERROR`로 실패한 생성 요청**은 최대 1분 정도 키를 계속 잡고 있을 수 있습니다. 같은 키와 본문으로 재시도하세요. 이전 시도가 아직 키를 잡고 있는 동안에는 `409 IDEMPOTENCY_KEY_IN_PROGRESS`가 반환되니, 시도 사이에 `retryAfterSeconds`(3초)만큼 기다리세요. 약 1분 안에 풀리며, 그 뒤의 재시도는 새 요청으로 실행됩니다. 2분이 지나도 풀리지 않으면 재시도를 멈추고 원인을 확인하세요. ## 속도 제한 계정이 보유한 키 개수와 무관하게, 모든 `/api/preview/*` 라우트에 대해 계정당 분당 60회 요청으로 제한됩니다. 제한을 넘으면 API는 다음 헤더와 함께 `429 RATE_LIMITED`를 반환합니다. | 헤더 | 값 | | - | - | | `Retry-After` | 제한이 초기화될 때까지 남은 초(`retryAfterSeconds`와 동일) | | `X-RateLimit-Limit` | 분당 제한 횟수 | | `X-RateLimit-Remaining` | `0` | | `X-RateLimit-Reset` | 제한이 초기화되는 유닉스 타임스탬프(초) | 이 헤더들은 `429`에만 포함됩니다. 멱등 생성 요청에서는 이미 사용된 키의 재생(replay), 충돌, 처리 중 응답은 속도 제한 횟수에 포함되지 않습니다. ### 동시에 실행 중인 요청 계정은 보유한 키 개수와 무관하게 모든 `/api/preview/*` 라우트에서 동시에 실행 중인 요청을 최대 10개까지 가질 수 있습니다. 11번째 요청은 `Retry-After: 1`과 함께 `429 TOO_MANY_CONCURRENT_REQUESTS`로 거절되며, `X-RateLimit-*` 헤더는 없습니다. 아직 끝나지 않은 요청을 세므로, 분당 60회보다 한참 적게 보내도 적용될 수 있습니다. 요청을 한꺼번에 보내지 말고 하나씩, 또는 몇 개씩 나눠 보내세요. 거절된 요청은 아무것도 하지 않았으므로 그대로 재시도해도 안전하지만, `Retry-After`만큼 기다린 뒤에 보내세요. 거절된 요청도 분당 60회에 포함됩니다. 단, 멱등 생성 요청은 요청이 받아들여진 뒤에만 이 횟수를 사용합니다. ## 에러 코드 ### 인증과 접근 모든 엔드포인트에서 반환될 수 있습니다. | 코드 | HTTP | 재시도 가능 | 원인과 대응 | | - | - | - | - | | `UNAUTHORIZED` | 401 | 아니요 | `Authorization` 헤더가 없거나 형식이 잘못되었거나, 알 수 없거나 폐기된 키입니다. 헤더(`Bearer dr_live_...`)를 확인하세요. 폐기된 키는 다시 쓸 수 없으니 **Settings → Developers**에서 새로 발급하세요. | | `NOT_FOUND` | 404 | 아니요 | 이 계정에서는 API를 사용할 수 없습니다(일부 계정에서만 사용할 수 있습니다). 모든 라우트가 존재하지 않는 라우트와 같은 `404` 상태로 응답합니다. 키에 연결된 계정이 더 이상 존재하지 않는 드문 경우에도 반환됩니다. DocuRise에 문의하세요. | | `PLAN_REQUIRED` | 403 | 아니요 | 요금제에 API 접근이 포함되어 있지 않습니다. 자동화를 멈추고 사람에게 알리세요. API가 포함된 요금제로 바뀌면 다시 동작합니다. | | `PAST_DUE_RESTRICTED` | 403 | 아니요 | 계정의 결제가 연체되어 API 전체(읽기와 쓰기)가 일시정지되었습니다. 자동화를 멈추고 대시보드에서 결제 수단을 업데이트하도록 사람에게 알리세요. 결제가 성공하면 접근은 저절로 복구됩니다. | | `INSUFFICIENT_SCOPE` | 403 | 아니요 | 키에 이 엔드포인트가 요구하는 범위가 없습니다. `message`에 필요한 범위가 표시됩니다. **Settings → Developers**의 **권한 수정**에서 범위를 추가하세요(키 자체는 바뀌지 않습니다). [인증](https://docurise.io/docs/ko/authentication.md) 참고. | ### 속도 제한과 가용성 | 코드 | HTTP | 재시도 가능 | 원인과 대응 | | - | - | - | - | | `RATE_LIMITED` | 429 | 예 | 계정의 분당 60회 요청을 넘었습니다. `Retry-After`초만큼 기다린 뒤 재시도하세요. 자세한 내용은 위의 속도 제한 절을 참고하세요. | | `TOO_MANY_CONCURRENT_REQUESTS` | 429 | 예 | 계정에서 이미 10개의 요청이 동시에 실행 중입니다. 하나가 끝날 때까지 기다린 뒤(`Retry-After`는 1초) 재시도하세요. 자세한 내용은 [동시에 실행 중인 요청](#동시에-실행-중인-요청)을 참고하세요. | | `RATE_LIMIT_UNAVAILABLE` | 503 | 예 | 속도 제한을 일시적으로 적용할 수 없습니다. 요청이나 키의 문제가 아닙니다. `retryAfterSeconds`(5) 후에 재시도하세요. | | `SERVICE_UNAVAILABLE` | 503 | 예 | API 키 확인을 일시적으로 할 수 없습니다. 키의 문제가 아닙니다. `retryAfterSeconds`(60) 후에 재시도하세요. `POST /segments`는 생성을 시작하지 못한 경우에도 이 코드를 반환합니다. 아무것도 만들어지지 않았으며, 같은 `Idempotency-Key`로 안전하게 재시도할 수 있습니다. 그룹 엔드포인트(`POST /segments`, `POST /segments/preview`, `GET /segments/{id}`)는 매우 무거운 규칙의 인원을 약 10초 안에 셀 수 없을 때도 이 코드를 반환합니다. 규칙을 단순하게 만들거나 다시 시도하세요. | | `INTERNAL_ERROR` | 500 | 예 | 요청을 처리하는 중 DocuRise 쪽에서 문제가 발생했습니다. 요청에는 문제가 없으니 간격을 늘려 가며 재시도하세요(생성 요청은 같은 `Idempotency-Key`로, [재시도](#재시도) 참고). 계속되면 DocuRise에 문의하세요. | API는 `502`와 함께 `BATCH_SCHEDULE_FAILED` 또는 `INSTAGRAM_UNAVAILABLE`을 반환할 수도 있습니다 ([Instagram](#instagram) 참고). 둘 다 재시도 가능합니다. ### 요청 형식 | 코드 | HTTP | 재시도 가능 | 원인과 대응 | | - | - | - | - | | `VALIDATION_ERROR` | 400 | 아니요 | 필드, 경로 또는 쿼리 파라미터가 올바르지 않습니다. 타입이나 값이 틀렸거나, 범위를 벗어났거나, 알 수 없거나 중복된 쿼리 파라미터, `q`나 요청 본문의 NUL 문자, 알 수 없는 본문 필드(폼 질문 안의 필드 포함), `content`와 `html`을 모두 보내거나 둘 다 보내지 않은 `kind: post` 생성(둘 중 정확히 하나만 보내세요), 200,000자를 넘는 `html`, RFC 3339가 아닌 날짜, 366일을 넘는 기간인 경우입니다. `message`에 해당 필드가 표시됩니다. 요청을 고치세요. `POST /segments`와 `POST /segments/preview`에서는 `name`이나 `filter`가 잘못된 경우(틀린 값, 20개를 넘는 조건 목록, UUID가 아닌 id, 조건이 허용하지 않는 키 조합)도 이 코드이며, `message`는 잘못된 부분의 경로로 시작합니다(예: `filter.conditions.2.value:`). `PATCH /documents/{id}`에서는 `If-Match`나 `If-Unmodified-Since`를 보낸 요청도 해당합니다(대신 본문에 `revision`을 보내세요). | | `INVALID_JSON` | 400 | 아니요 | 요청 본문이 올바른 JSON이 아닙니다. 본문이 있는 엔드포인트는 문서와 Instagram 규칙의 `POST`와 `PATCH`, 그리고 `POST /segments`와 `POST /segments/preview`입니다. | | `INVALID_CURSOR` | 400 | 아니요 | `cursor`가 이 API가 내 계정에 발급한 값이 아닙니다. 이전 페이지의 `nextCursor`를 받은 그대로 전달하거나, 커서 없이 처음부터 다시 조회하세요. 목록 엔드포인트에서만 반환됩니다. | | `INVALID_INPUT` | 400 | 아니요 | `POST /documents`: 요청 형식은 올바르지만 더 구체적인 코드가 없는 이유로 문서를 만들 수 없었습니다. [레퍼런스](https://docurise.io/docs/ko/api-reference/create-document.md)와 본문을 대조해 보세요. | ### 멱등 `POST /api/preview/documents`, `POST /api/preview/instagram/rules`, `POST /api/preview/segments`에는 `Idempotency-Key` 헤더가 필요합니다. `POST /api/preview/segments/preview`는 이 헤더를 받지 않습니다. 아무것도 저장하지 않으므로 반복 호출해도 항상 안전합니다. | 코드 | HTTP | 재시도 가능 | 원인과 대응 | | - | - | - | - | | `IDEMPOTENCY_KEY_REQUIRED` | 400 | 아니요 | `Idempotency-Key` 헤더가 없습니다. 논리적인 작업 하나마다 키를 하나씩 보내세요(UUID나, 요청을 일으킨 대상의 id). | | `IDEMPOTENCY_KEY_TOO_LONG` | 400 | 아니요 | 키가 255자를 넘습니다. 더 짧은 키를 사용하세요. | | `IDEMPOTENCY_KEY_CONFLICT` | 409 | 아니요 | 이 키가 이미 다른 본문(또는 다른 엔드포인트나 문서 `kind`)으로 사용되었습니다. 새 요청에는 새 키를 쓰고, 키 재사용은 동일한 요청을 재시도할 때만 하세요. | | `IDEMPOTENCY_KEY_IN_PROGRESS` | 409 | 예 | 이 키로 보낸 요청이 아직 처리 중이거나, 이전 시도가 `500 INTERNAL_ERROR`로 실패한 뒤에도 키를 잡고 있습니다. `retryAfterSeconds`(3)만큼 기다린 뒤 같은 키와 본문으로 재시도하세요. 첫 요청이 끝났다면 그 결과를 받고, 이전 시도가 실패한 경우에는 약 1분 안에 풀려 재시도가 새 요청으로 실행됩니다. | ### 문서 | 코드 | HTTP | 재시도 가능 | 반환하는 엔드포인트 | 원인과 대응 | | - | - | - | - | - | | `DOCUMENT_NOT_FOUND` | 404 | 아니요 | `/documents/{id}`와 그 애널리틱스 | 내 계정에 해당 문서가 없습니다. 알 수 없는 ID, 형식이 잘못된 ID, 다른 사람의 문서는 모두 구분되지 않습니다. ID를 확인하세요(예: `GET /documents`와 대조). | | `DOCUMENT_LIMIT_REACHED` | 403 | 아니요 | `POST /documents`, `PATCH /documents/{id}` | 생성하거나 게시하면 요금제의 게시 문서 한도를 넘습니다. 초안은 포함되지 않습니다. 자동화를 멈추고, 대시보드에서 문서를 정리하거나 요금제를 바꾸도록 사람에게 알리세요. `details`는 없습니다. | | `PRECONDITION_REQUIRED` | 428 | 아니요 | `PATCH /documents/{id}` | 본문에 `revision`이 없습니다. `GET /documents/{id}`로 문서를 조회하고 그 `revision`을 PATCH 본문에 넣어 보내세요. | | `REVISION_CONFLICT` | 409 | 아니요 | `PATCH /documents/{id}` | 조회한 이후에 문서가 (대시보드나 API에서) 바뀌었고, 아무것도 저장되지 않았습니다. 응답의 `ETag` 헤더에 현재 `revision` 값이 있습니다. `GET`으로 문서를 다시 조회해 지금 내용에 변경을 다시 적용하고, 새 `revision`으로 보내세요. 그대로 다시 보내지 마세요. | | `PROTECTION_RULE_CONFLICT` | 422 | 아니요 | `PATCH /documents/{id}` | 보호 설정 변경이 문서 구성과 충돌합니다(예: 이메일을 반드시 수집해야 하는 문서에 `requireEmail: false`, 폼에 접근 제어 설정). 아무것도 적용되지 않았습니다. `details.rule`에 해당 규칙이 표시되며, 새 값이 추가될 수 있습니다. 요청을 바꾸거나 대시보드에서 문서를 수정하세요. | | `STATUS_NOT_SUPPORTED` | 422 | 아니요 | `POST /documents`, `PATCH /documents/{id}` | `status` 값은 올바르지만 이 문서에는 쓸 수 없습니다. `draft`는 포스트와 폼에만 있고, 초안은 `inactive`로 바꿀 수 없으며(먼저 게시하세요), `inactive`는 생성 시점에 지정할 수 없습니다. 문서가 지원하는 상태를 보내세요. | | `CANNOT_REVERT_TO_DRAFT` | 422 | 아니요 | `PATCH /documents/{id}` | 게시된 포스트나 폼은 `draft`로 되돌릴 수 없습니다. 공개를 중단하려면 `inactive`를 사용하세요. | | `DOCUMENT_NOT_READY` | 422 | 아니요 | `PATCH /documents/{id}` | 문서 파일이 아직 업로드되거나 처리되는 중입니다. 처리가 끝난 뒤(몇 초가 아니라 몇 분 단위) 다시 시도하세요. | | `RELATIVE_EXPIRY_NOT_SUPPORTED` | 422 | 아니요 | `PATCH /documents/{id}` | 문서가 열람자별 상대 만료를 사용하고 있어 API로는 바꿀 수 없습니다. 대시보드에서 변경하세요. | | `EMPTY_BODY` | 422 | 아니요 | `POST /documents`, `PATCH /documents/{id}` | 내용이 없는 포스트가 공개되려 했습니다. 텍스트, 이미지 또는 동영상을 추가하거나 `draft`로 생성하세요. | | `UNSUPPORTED_VARIABLE` | 422 | 아니요 | `POST /documents`, `PATCH /documents/{id}` | 게시된 포스트에서는 채울 수 없는 `{recipient_name}` 같은 이메일 변수가 포함된 채 공개되려 했습니다. 변수를 지우거나 `draft`로 생성하세요. | | `VIDEO_FAILED` | 422 | 아니요 | `PATCH /documents/{id}` | 초안 게시 시: 포스트의 동영상 처리에 실패했습니다. 대시보드 편집기에서 동영상을 지우거나 다시 업로드하세요. | | `VIDEO_OVER_LIMIT` | 422 | 아니요 | `PATCH /documents/{id}` | 초안 게시 시: 포스트의 동영상이 허용 길이보다 깁니다. 대시보드 편집기에서 더 짧은 동영상으로 바꾸세요. | | `BROADCAST_BACKED_POST` | 422 | 아니요 | `PATCH /documents/{id}` | 초안 게시 시: 이 포스트는 이메일 1회성 발송의 본문이라, 이 엔드포인트가 아니라 이메일 발송 흐름으로 게시됩니다. | | `PAID_LEAD_GATE_NO_PRODUCTS` | 422 | 아니요 | `PATCH /documents/{id}` | 게시하거나 다시 활성화하면, 가격이 있는데 열람자가 구매할 수 있는 상품이 없는 문서가 공개됩니다. 먼저 대시보드에서 상품을 정리하세요. | | `SLUG_TAKEN` | 409 | 아니요 | `PATCH /documents/{id}` | 초안 게시 시: 이 문서에 생성된 웹 주소를 같은 순간 다른 문서가 가져갔습니다. 아무것도 게시되지 않았습니다. 문서를 다시 조회한 뒤 현재 `revision`으로 요청을 다시 보내세요. | | `NOTION_FETCH_FAILED` | 422 | 경우에 따라 | `POST /documents` (`kind: notion`) | Notion 페이지를 가져올 수 없었습니다. `details.notionErrorCode`에 이유가 있습니다(예: `NOTION_ERROR_PRIVATE`는 페이지가 웹에 게시되지 않은 경우). `retryable`이 `true`이면(네트워크 문제나 Notion 속도 제한) 같은 키로 재시도하고, 아니면 페이지나 URL을 고친 뒤 새 키를 쓰세요. | | `VIDEO_CONTENT_UNSUPPORTED` | 422 | 아니요 | `POST /documents` (`kind: post`) | 업로드한 동영상의 자리표시자(`data-video-id`)가 있는 포스트 내용은 API로 생성할 수 없습니다. 이를 빼거나 대시보드 편집기에서 동영상을 추가하세요. `content`의 YouTube와 Vimeo 임베드(`data-video-embed`)는 허용됩니다. | | `FORM_FILE_QUESTION_DISABLED` | 403 | 아니요 | `POST /documents` (`kind: form`) | 이 계정에서는 아직 `file` 질문 유형을 사용할 수 없습니다. 다른 질문 유형을 사용하세요. | | `HTML_MODE_DISABLED` | 403 | 아니요 | `POST /documents` (`kind: post`, `html`) | 이 계정에서는 HTML 포스트를 사용할 수 없으며, 아무것도 생성되지 않았습니다. 대신 `content`로 포스트를 만들거나, 계정에서 HTML 포스트를 쓸 수 있도록 요청하세요. | | `HTML_REJECTED` | 422 | 아니요 | `POST /documents` (`kind: post`, `html`) | 서버가 HTML을 받아들일 수 없었으며, 아무것도 생성되지 않았습니다. `details.reason`에 이유가 있습니다: `too_large`(정제 후 포스트 크기 한도 초과), `css_rejected`(`