콘텐츠로 이동
GJ Kit

OUTCOME_QUERY_FIRST_ERROR_CODES — @gj-kit/toss-payments

@gj-kit/toss-payments/server에서 공개하는 constant입니다. package version 0.6.1의 release declaration을 그대로 표시합니다.

검증된 import 예제

섹션 제목: “검증된 import 예제”
import { OUTCOME_QUERY_FIRST_ERROR_CODES } from '@gj-kit/toss-payments/server';

시그니처, 매개변수, 반환 타입

섹션 제목: “시그니처, 매개변수, 반환 타입”
OUTCOME_QUERY_FIRST_ERROR_CODES: readonly string[]

이 선언은 매개변수, optionality, 제네릭, 반환값, 공개 union/type 계약의 정본입니다. 호출 전 필요한 환경·권한·오류 경계는 패키지 Golden path와 이 subpath의 import 조건을 함께 확인하세요.

Release context

섹션 제목: “Release context”
  • 패키지: @gj-kit/toss-payments
  • 버전: 0.6.1
  • 공개 entry: ./server
  • 소스: GitHub

구현 주석

섹션 제목: “구현 주석”

Toss error codes after which the caller must look the outcome up (getPaymentByOrderId / getPayment) before retrying with a new key or marking the operation failed — the provider may have completed (or be completing) the operation even though the response is an error. Marking such an operation FAILED without a lookup is how “money left, user told it failed” incidents happen.

Membership reasons (classification from classifyTossErrorCode):

  • ALREADY_PROCESSED_PAYMENT (400, STATE, not retryable) — a confirm for this paymentKey was already completed, typically by a refreshed page or a duplicate worker. The outcome exists; fetch it and treat it as success rather than failure.
  • IDEMPOTENT_REQUEST_PROCESSING (409, CONCURRENCY) — the original request with this key is still in flight. Documented instruction: request again and read the result.
  • FORBIDDEN_CONSECUTIVE_REQUEST (403, CONCURRENCY) — a back-to-back request on the same resource was refused; the earlier one may have succeeded.
  • PROVIDER_ERROR (400, TRANSIENT) — the upstream institution (card company/bank) failed mid-flight; Toss may hold a partially recorded state. 400 but retryable, which is why the HTTP status must never drive this decision.
  • FAILED_INTERNAL_SYSTEM_PROCESSING, FAILED_PAYMENT_INTERNAL_SYSTEM_PROCESSING, COMMON_ERROR (500, TRANSIENT) — Toss-side processing failed after the request was accepted; whether the ledger moved is unknown.
  • FAILED_REFUND_PROCESS, FAILED_METHOD_HANDLING_CANCEL, FAILED_PARTIAL_REFUND (500, TRANSIENT) — cancel/refund failed on bank latency or method handling; the bank may have executed the refund. Re-fetch the payment and compare balanceAmount/cancels.
  • FAILED_BILLING_AUTO_CANCEL (500, TRANSIENT) — the automatic reversal of a billing charge failed transiently; the charge and/or its reversal may exist.
  • FAILED_BILL_KEY_AUTH_CREATION (500, TRANSIENT) — billing-key issuance failed mid-way. Toss has no billing-key lookup API, so the “lookup” here is your own BillingKeyStore: check whether a key was already persisted for the customer before issuing again.

Invariant kept by this table: every code the library marks retryable: true is in this set, because retryable means “worth retrying with a new key after judgment” (README §5) and that judgment is exactly an outcome lookup. The unit suite checks it against CLASSIFIED_TOSS_ERROR_CODES (the code table’s own keys), so adding a retryable code to the table without adding it here fails CI. Deliberately excluded: NOT_MATCHES_REFUNDABLE_AMOUNT (measured: the cancel was not executed — re-fetch to recompute the amount, but there is no outcome uncertainty), every REJECTED/AUTH/REQUEST/AMOUNT/DEADLINE code (definitive refusals), and unregistered codes (the library cannot vouch for them; apply your own policy for unknown 5xx responses).