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:
request_approval: the charge waits for the user. Send them theapprove_url.request_new_mandate: the mandate can't cover this. Ask the user to sign a new one.none: fix the request, or stop.
Policy denials return HTTP 402 and include the recorded charge.
| code | Message | next_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 |
link_expired |
This link has expired. 링크가 만료됐어요. |
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 |