Forlabs Vault docs

Errors

Every error uses the same envelope: {type, code, message, param, doc_url, request_id, next_action}. message follows Accept-Language (ko/en). doc_url links to the row for its code on this page.

next_action tells the agent what to do next:

Policy denials return HTTP 402 and include the recorded charge.

codeMessagenext_action
already_processed This request was already processed.
이미 처리된 요청이에요.
none
approval_expired The approval request expired.
승인 요청이 만료됐어요.
none
approval_rejected The user declined this payment.
사용자가 결제를 거절했어요.
none
approval_required The charge needs the user's approval. See the approval flow in the quickstart. request_approval
assertion_invalid The passkey assertion is invalid.
패스키 서명을 검증하지 못했어요.
none
authentication_required An API key is required.
API 키가 필요해요.
none
challenge_invalid The challenge expired or was already used.
서명 요청이 만료됐거나 이미 사용됐어요.
none
currency_mismatch Currency differs from the mandate.
위임장과 통화가 달라요.
request_new_mandate
currency_not_supported This currency is not supported.
이 통화는 지원하지 않아요.
none
forbidden Not accessible from this tenant.
이 테넌트에서 접근할 수 없어요.
none
idempotency_key_required The Idempotency-Key header is required.
Idempotency-Key 헤더가 필요해요.
none
idempotency_key_reused This Idempotency-Key was already used with a different request.
같은 Idempotency-Key로 다른 요청이 이미 처리됐어요.
none
instrument_mismatch The instrument differs from the one signed in the mandate.
위임장에 서명된 결제수단이 아니에요.
request_new_mandate
instrument_not_found Payment instrument not found.
결제수단을 찾을 수 없어요.
none
invalid_amount The amount is invalid.
금액이 올바르지 않아요.
none
invalid_api_key The API key is invalid.
API 키가 올바르지 않아요.
none
invalid_request The request is malformed.
요청 형식이 올바르지 않아요.
none
invalid_user_token The user token could not be verified.
사용자 토큰을 확인할 수 없어요.
none
invalid_webhook_url Webhook URLs must be https (http://localhost only in test mode).
웹훅 URL은 https여야 해요. 테스트 모드에서만 http://localhost를 쓸 수 있어요.
none
mandate_exceeds_tenant_cap The proposed mandate exceeds the tenant cap.
위임장 한도가 테넌트 상한을 넘어요.
none
mandate_expired The mandate has expired.
만료된 위임장이에요.
request_new_mandate
mandate_integrity_failed The mandate no longer matches what the user signed, so payment was stopped. Contact support.
위임장이 사용자가 서명한 내용과 달라 결제를 멈췄어요. 고객 지원에 알려 주세요.
none
mandate_not_active The mandate is not active.
유효한 위임장이 아니에요.
request_new_mandate
mandate_not_yet_valid The mandate is not yet valid.
아직 시작되지 않은 위임장이에요.
none
mandate_revoked The mandate was revoked.
철회된 위임장이에요.
request_new_mandate
merchant_not_allowed The merchant is not allowed by the mandate.
위임장에서 허용하지 않은 사용처예요.
request_new_mandate
not_found Not found.
대상을 찾을 수 없어요.
none
per_charge_limit_exceeded The amount exceeds the per-charge limit.
1회 최대 금액을 넘어요.
request_new_mandate
rail_error The payment rail returned an error.
결제사에서 오류가 났어요.
none
rail_not_configured No credentials are configured for this rail.
결제 레일 설정이 없어요.
none
rate_limited Too many requests. Try again later.
요청이 너무 많아요. 잠시 후 다시 시도해 주세요.
none
registration_not_allowed This user already has a passkey.
이미 패스키가 등록된 사용자예요.
none
return_url_not_registered return_url is not registered for this tenant.
등록되지 않은 return_url이에요.
none
sandbox_only Only sandbox tenants may use this. Send user_token and instrument_id.
샌드박스 테넌트에서만 쓸 수 있어요. user_token과 instrument_id를 보내 주세요.
none
total_limit_exceeded The amount exceeds the remaining total limit.
남은 총 한도를 넘어요.
request_new_mandate