오류 | Proxy-seller

x402 API는 실제 HTTP 상태 코드를 사용합니다. 모든 오류는 동일한 JSON 본문을 가지며, retry_action 대리인에게 다음에 무엇을 해야 할지 알려줍니다.

오류 내용

이름	유형	설명
오류	문구	오류 코드에 대해서는 아래 표를 참조하십시오.
메시지	문구	사람이 읽기 쉬운 짧은 메시지
재시도 가능	부울	반복이 도움이 될지 여부
retry_action	문구	작업 내용: `resign`, `retry_same_payment`, `poll`, `wait_and_retry`, `abandon`, `human_required`
retry_after_seconds	정수	재시도 시점; 다음과 동일합니다. `Retry-After` 헤더
payment_state	문구	`unused`, `in_flight` 또는 `settled` — 자금이 빼앗겼는지 여부 (재시도 및 이뎀포텐시)
authorization_expires_at	문구	승인 권한이 유효한 기간까지; 그 전에는 새로운 승인서에 서명하지 마십시오.
order_id, operation_id, poll_url	문구	결제가 적용되는 순서 및 해당 결제 방식(해당하는 경우)
bound_wallet	문구	`quote_bound_to_other_wallet`: 인용문을 담는 지갑
facilitator_reason	문구	지급 확인 실패 사유(고정된 목록에서 선택) 또는 `unknown`
상세 정보	문구	예시: 유효하지 않은 필드의 경로와 같은 세부 사항: `/items/0/qty: …`

새로운 인용문이 포함된 답변 (quote_expired, payment_expired, quote_bound_to_other_wallet)에는 인용문 필드와 PAYMENT-REQUIRED 헤더.

{
    "error": "payment_not_settleable",
    "message": "The presented authorization can still be settled",
    "retryable": true,
    "retry_action": "wait_and_retry",
    "retry_after_seconds": 512,
    "payment_state": "unused",
    "authorization_expires_at": "2026-11-02T10:16:00Z"
}

작업 재시도

retry_action	작업 내용
`resign`	이 답변에 포함된 새로운 요구 사항에 서명하십시오 (`PAYMENT-REQUIRED`), 또는 요청을 수정해 주세요
`retry_same_payment`	동일한 요청을 동일한 `PAYMENT-SIGNATURE`. 새로운 문서에 서명하지 마십시오
`poll`	In `202` 응답: 설문조사 `poll_url`
`wait_and_retry`	다음 날짜보다 이른 시점이 아닌, 다시 시작하십시오(새로운 인용문, 새로운 서명). `retry_after_seconds`
`abandon`	동일한 요청을 반복해도 도움이 되지 않습니다.
`human_required`	고객 지원팀에 문의하십시오. 새로운 승인서에 서명하지 마십시오.

오류 코드

오류	HTTP	retry_action	~할 때
`payment_required`	402	`resign`	유료 엔드포인트가 호출되었으나 `PAYMENT-SIGNATURE`: 인용문은 답변에 포함되어 있습니다
`payment_invalid`	402	`abandon`	결제 헤더 형식이 잘못되었거나 x402 버전 2가 아닙니다 (`X-PAYMENT` (버전 1 포함); 잘못된 네트워크, 자산, 수취인, 금액 또는 유효 기간; 서명 확인 실패; 다른 지갑에서 결제된 갱신 또는 트래픽
`insufficient_funds`	402	`wait_and_retry`	지갑에 USDC 잔액이 부족합니다. 지갑에 잔액을 충전한 후, 인증이 유효한 동안 동일한 요청을 다시 시도하십시오.
`quote_expired`	402	`resign`	견적 기간이 만료되었거나 이미 결제가 완료되었으며, 귀하의 승인 권한도 만료되었습니다. 응답에 새로운 견적이 포함되어 있습니다.
`payment_expired`	402	`resign`	승인 권한이 사용되지 않은 채 만료되었거나 취소되었습니다. 아무것도 가져가지 않았습니다. 응답에 새로운 견적이 포함되어 있습니다.
`invalid_request`	400	`abandon`	잘못된 필드, 알 수 없는 필드, 잘못된 JSON, 본문 크기가 64 KiB를 초과함; 국가, 기간, 수량, 등급, 패키지 또는 옵션이 제공되지 않음; 두 번째 주거용 패키지; 특정 엔드포인트의 규칙
`terms_not_accepted`	400	`resign`	`accept_terms` 버전이 최신이 아닙니다. 본문에는 다음 내용이 포함되어 있습니다. `offer_version` 그리고 `privacy_version`
`purpose_not_allowed`	403	`abandon`	`intended_use` 카탈로그 목록에 없습니다
`wallet_rejected`	403	`abandon`	지갑이 차단되었거나 제재 목록에 등재되어 있습니다.
`unauthorized`	401	`abandon`	아니요 `Authorization: Bearer x402_…` 헤더; 지갑 서명이 챌린지와 일치하지 않습니다.
`order_not_found`	404	`abandon`	해당 명령어가 존재하지 않거나, 해당 토큰이 유효하지 않습니다.
`not_found`	404	`abandon`	충전 또는 챌린지가 존재하지 않거나, 해당 토큰이 사용 불가합니다.
`payment_replayed`	409	`abandon`	동일한 인증 정보(payer 및 nonce)가 서로 다른 콘텐츠와 함께 제공되었습니다.
`payment_not_settleable`	409	`wait_and_retry`	인용문은 더 이상 유효하지 않지만, 귀하의 승인 요청은 여전히 처리될 수 있습니다. 다음까지 기다려 주십시오. `authorization_expires_at` 새로운 계약에 서명하기 전에
`payment_under_review`	409	`human_required`	지급 내역은 현재 당사 담당자가 검토 중입니다.
`quote_bound_to_other_wallet`	409	`resign`	다른 지갑에서 이미 이 인용문을 사용했습니다. 응답에 새로운 인용문이 포함되어 있습니다.
`quote_payment_in_progress`	409	`wait_and_retry`	이 견적에 대한 또 다른 결제가 처리 중입니다.
`quote_config_mismatch`	409	`abandon`	유료 의뢰의 본문 내용이 견적서와 일치하지 않거나, 유료 승인 요청이 중복되어 또 다른 의뢰가 발생한 경우
`idempotency_key_conflict`	409	`abandon`	귀하의 지갑에서 이미 이 기능을 사용했습니다. `idempotency_key` 지난 24시간 동안의 또 다른 결제
`rate_limited`	429	`wait_and_retry`	한도를 초과했습니다 (제한 사항)
`settlement_retry`	503	`retry_same_payment`	결제 처리가 아직 진행 중입니다. 다음에서 동일한 요청을 다시 제출해 주십시오. `retry_after_seconds`
`channel_paused`	503	`wait_and_retry`	현재 이 서비스는 일시적으로 새로운 결제를 받지 않고 있습니다.
`dependency_unavailable`	503	`wait_and_retry`	일시적인 오류: 가격, 상품 목록, 결제 확인 또는 기타 서비스를 이용할 수 없습니다.
`internal_error`	500	`wait_and_retry`	예기치 않은 오류

잘못된 HTTP 메서드를 반환하면 405 코드와 함께 invalid_request.

이 서비스의 모든 응답에는 다음이 포함됩니다. X-Request-Id 헤더. 문제를 신고할 때 지원팀에 이 정보를 제공해 주세요.

오류

오류 내용

작업 재시도

오류 코드

On this page