API 오류 — 각 코드의 의미와 해결 방법

FastOG는 요청이 실패하면 기계가 읽을 수 있는 오류 코드를 반환합니다. 서명된 OG 이미지 렌더링 요청이든, 제품 내 관리자 화면 중 하나에 대한 호출이든 마찬가지입니다. 모든 오류 응답에는 다음이 포함됩니다.

• error — 레거시 짧은 토큰입니다. 이전 클라이언트가 계속 동작하도록 모든 실패 응답에 여전히 포함됩니다.
• code — 동일한 안정적이고 문서화된 오류 코드(아래 표)이며, 공개 API가 사용하는 이름으로 제공됩니다.
• message — 무엇이 잘못되었는지에 대한 한 문장 설명입니다.
• hint — 무엇이 잘못되었고 어떻게 해결해야 하는지에 대한 짧고 평이한 설명입니다.
• docs_url — 해당 코드의 섹션으로 연결되는 이 페이지 링크입니다.
• request_id — 이 HTTP 실패를 대시보드 Render Logs 표의 행과 연결합니다(X-Request-ID 응답 헤더에도 반환됩니다). 연결할 대상이 없는 화면은 null로 응답하지만, 이 키는 항상 존재합니다.

제품 내 화면인 Shopify admin, WooCommerce Studio, Wix bridge, 데모는 아래 코드에 대해 동일한 응답 봉투(envelope)로 응답하므로, 어디서 마주치든 실패의 의미는 같습니다. 모듈 화면은 특정 코드에 대해 기존에 반환하던 HTTP 상태를 유지할 수 있습니다(예를 들어 render_failed는 커버 내보내기에서 503, 공개 API에서 502로 응답합니다). 코드, 메시지, 힌트, 문서 링크는 바뀌지 않습니다.

오류 응답 읽기

{
  "error": "invalid_signature",
  "code": "invalid_signature",
  "message": "The signature does not match.",
  "hint": "The signature did not match. Re-sign with your HMAC secret after every param change.",
  "request_id": "5f2a9c1e-..."
}

이해할 수 없는 응답을 받았다면, 가장 빠른 방법은 다음과 같습니다.

1. code을 확인합니다.
2. URL 빌더를 점검합니다 — 대부분의 실패는 계정 문제가 아니라 서명 버그입니다.
3. 아래 코드에서 정확한 원인과 해결 방법을 찾습니다.
4. 대시보드에서 Render Logs를 열고 동일한 error_code로 필터링합니다 — 각 행에 요청된 파라미터가 표시되므로 재현할 수 있고, request_id이 일치하는지도 확인할 수 있습니다.

서명 및 인증

missing_signature

요청에 key 및/또는 s(서명) 쿼리 파라미터가 누락되었습니다.

해결: URL에 key=<api-key>과 s=<hmac-signature>가 모두 포함되어 있는지 확인하십시오. SDK 또는 /docs/hmac-signature-guide 안내를 사용하여 URL을 구성하십시오.

invalid_signature

s 값이 이 URL에 대해 HMAC 시크릿이 생성한 값과 일치하지 않습니다.

해결: 서명은 s을 제외한 모든 쿼리 파라미터를 키 기준으로 정렬하여 포함합니다. 파라미터를 변경하면 — 순서 변경, URL 인코딩 차이, 공백 추가를 포함하여 — 서명이 무효화됩니다. 변경할 때마다 다시 서명하십시오. 시크릿이 API 키 생성 시 표시된 것과 동일한지 확인하십시오.

invalid_signature_format

s 값이 64자 hex 문자열이 아닙니다.

해결: 서명은 raw SHA-256 hex(소문자 a-f0-9)여야 합니다. 출력을 base64로 인코딩하거나 잘라내고 있다면 일반 hex를 사용하십시오.

expired_timestamp

제공한 t 타임스탬프가 5분을 초과하여 오래되었습니다.

해결: URL을 구성할 때마다 타임스탬프를 다시 생성하십시오. 이 코드는 레거시 서명 URL 흐름에 적용되며, 현재의 HMAC v2 흐름에는 타임스탬프가 없습니다.

invalid_api_key

전달한 key이(가) 존재하지 않습니다.

해결: 대시보드에서 전체 API 키를 복사하십시오. sk_으로 시작하는 공개 식별자입니다. 이 값은 공개되어 있으며 URL에 포함해도 안전합니다. 소유권을 증명하는 것은 URL에 절대 포함되지 않는 시크릿입니다.

missing_hmac_secret

API 키에 HMAC 시크릿이 구성되어 있지 않습니다.

해결: 대시보드에서 새 API 키를 생성하십시오. HMAC 시크릿은 생성 시 한 번만 생성되어 표시됩니다.

매개변수 / 입력

invalid_image_url

URL을 포함하는 prop(image, brand_logo, logo, avatar, background_image, ...)이 공개 http(s) URL이 아닙니다.

수정: 공개적으로 가져올 수 있는 https://... URL을 전달하십시오. 서버 측 요청 위조를 방지하기 위해 localhost, 사설 IP, 그리고 경로만 있는 값은 거부됩니다.

구독

subscription_required (402)

요청이 Dynamic API에 도달했지만 계정에 활성 플랜이 없습니다. API 접근은 구독 전용입니다. 플랜이 게이트 역할을 하며, FastOG 앱에서 판매하는 것과 동일한 커버리지 + 기능 사다리를 제공합니다. 렌더링 자체는 과금되지 않습니다. 월간 렌더 할당량도, 초과 요금도 없습니다.

해결: 대시보드에서 Dynamic API 플랜을 선택하고 API 키를 생성하십시오. 응답에는 플랜 페이지를 가리키는 top_up_url이 포함됩니다.

렌더 서비스

store_blocked (403)

이 키 뒤에 있는 스토어의 렌더링이 FastOG에 의해 일시 중지되었습니다(예: 남용 또는 과도한 사용). 엣지에 이미 캐시된 커버는 만료될 때까지 계속 제공될 수 있습니다. 해결하려면 지원팀에 문의하십시오. 요청에서 변경할 수 있는 사항으로는 이 문제가 해결되지 않습니다.

render_unreachable

렌더 서비스에 연결할 수 없습니다(짧은 재시작 구간).

해결: 몇 초 후에 다시 시도하십시오. 이 시도에 대한 렌더는 집계되지 않았습니다.

render_failed

렌더 서비스가 요청에 대해 오류를 반환했습니다.

해결: 템플릿 props를 확인하십시오. 값이 너무 길거나 형식이 잘못되었거나, 지원되지 않는 필드가 있거나, 업스트림 이미지에 연결할 수 없는 경우입니다. 응답에는 근본 원인이 되는 status이 포함됩니다. 렌더는 집계되지 않았습니다.

스토어 관리자 화면

이 코드들은 Shopify 관리자와 WooCommerce Studio, 즉 판매자가 서명된 API가 아니라 실제로 작업하는 임베디드 편집기에서 응답합니다. 일부는 공개 API와 공유되며(invalid_image_url, render_failed, invalid_signature), 해당 항목은 위에 문서화된 내용을 그대로 유지합니다.

Wix 브리지

Wix 브리지는 판매자 세션이 아니라 Wix 앱이 서명하므로, 이 브리지의 실패는 앱 개발자에게 귀속됩니다. 모든 응답에는 여전히 code과 request_id이 포함되며, 브리지 요청 id는 서명된 봉투(envelope)의 id입니다.

데모 표면

데모는 판매자용 엔드포인트가 아니라 소유자 전용 판매 콘솔입니다.

범위 지정 규칙 편집기 코드

범위 지정 규칙 편집기(Shopify admin 및 WooCommerce Studio)는 이러한 토큰을 판매자의 자체 언어로 직접 번역하므로, 해당 응답에는 error과 code이 포함되지만 hint은 포함되지 않습니다. 두 번째 영어 설명은 판매자가 실제로 보는 현지화된 설명과 어긋나기만 할 뿐입니다:

scope_already_defined, scoped_rule_limit_reached, scoped_rules_not_on_plan, scope_value_required, scope_value_too_long, unknown_scope_type, base_rule_required, scoped_rules_product_only, cannot_delete_base_rule.

계속 막혀 있나요?

• 대시보드의 Render Logs 페이지를 여십시오. 모든 결과(성공 + 거부)가 해당 error_code, HTTP 상태, 요청된 파라미터와 함께 나열됩니다.
• 서명된 URL에서 php artisan og:diagnose을 실행하여 전체 파이프라인을 따라가며 어느 단계에서 실패하는지 확인하십시오.
• 사용 중인 프레임워크(Next.js, Express, SvelteKit, ...)에 대한 문서를 사이드바에서 확인하십시오.