Errores

La API x402 utiliza códigos de estado HTTP reales. Cada error tiene el mismo cuerpo JSON, y retry_action indica a tu agente qué debe hacer a continuación.

Cuerpo del error

Nombre	Tipo	Descripción
error	Cadena	Código de error: consulta la tabla siguiente
mensaje	Cadena	Mensaje breve y fácil de entender
repetible	Booleano	¿Puede ayudar la repetición?
retry_action	Cadena	Qué hay que hacer: `resign`, `retry_same_payment`, `poll`, `wait_and_retry`, `abandon`, `human_required`
retry_after_seconds	Número entero	Cuándo volver a intentarlo; equivale a `Retry-After` encabezado
payment_state	Cadena	`unused`, `in_flight` o `settled` — si se sustrajeron los fondos (Reintentos e idempotencia)
authorization_expires_at	Cadena	Hasta cuándo sigue siendo válida tu autorización; no firmes una nueva antes de
order_id, operation_id, poll_url	Cadena	El número de pedido y la operación a la que corresponde el pago, cuando existan
bound_wallet	Cadena	`quote_bound_to_other_wallet`: la cartera que contiene la cita
facilitator_reason	Cadena	Motivo del fallo en el pago, de una lista fija, o `unknown`
detalle	Cadena	Detalles, por ejemplo, la ruta del campo no válido: `/items/0/qty: …`

Respuestas con una nueva cita (quote_expired, payment_expired, quote_bound_to_other_wallet) también contienen los campos de cita y el PAYMENT-REQUIRED encabezado.

{
    "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"
}

Reintentar acciones

retry_action	Qué hay que hacer
`resign`	Firma los nuevos requisitos de esta respuesta (`PAYMENT-REQUIRED`), o corrige la solicitud
`retry_same_payment`	Envía la misma solicitud con el mismo `PAYMENT-SIGNATURE`. No crees uno nuevo
`poll`	En `202` respuestas: encuesta `poll_url`
`wait_and_retry`	Empieza de nuevo (nueva cita, nueva firma) no antes de `retry_after_seconds`
`abandon`	Repetir la misma solicitud no servirá de nada.
`human_required`	Ponte en contacto con el servicio de asistencia. No firmes una nueva autorización.

Códigos de error

error	HTTP	retry_action	Cuando
`payment_required`	402	`resign`	Se ha llamado a un punto final de pago sin `PAYMENT-SIGNATURE`: la cita aparece en la respuesta
`payment_invalid`	402	`abandon`	El encabezado de pago tiene un formato incorrecto o no cumple con la norma x402 versión 2 (`X-PAYMENT` (incluida la versión 1); red, activo, destinatario, importe o periodo de validez incorrectos; error en la verificación de la firma; una renovación o tráfico pagado por otro monedero
`insufficient_funds`	402	`wait_and_retry`	El monedero no tiene suficientes USDC. Recarga el monedero y repite la misma solicitud mientras la autorización siga siendo válida.
`quote_expired`	402	`resign`	El presupuesto ha caducado o ya se ha pagado, y tu autorización también ha caducado. En la respuesta encontrarás un nuevo presupuesto.
`payment_expired`	402	`resign`	La autorización caducó sin haberse utilizado o fue cancelada. No se ha cobrado nada. En la respuesta figura un nuevo presupuesto.
`invalid_request`	400	`abandon`	Campo no válido, campo desconocido, JSON no válido, cuerpo superior a 64 KiB; país, periodo, cantidad, nivel, paquete u opciones no disponibles; un segundo paquete residencial; reglas del punto final específico
`terms_not_accepted`	400	`resign`	`accept_terms` Las versiones no están actualizadas. El cuerpo contiene `offer_version` y `privacy_version`
`purpose_not_allowed`	403	`abandon`	`intended_use` no figura en la lista del catálogo
`wallet_rejected`	403	`abandon`	El monedero está bloqueado o figura en una lista de sanciones
`unauthorized`	401	`abandon`	No `Authorization: Bearer x402_…` encabezado; la firma del monedero no coincide con el desafío
`order_not_found`	404	`abandon`	El orden no existe o el token no es válido para él.
`not_found`	404	`abandon`	La recarga o el desafío no existen, o la ficha no es válida para ello.
`payment_replayed`	409	`abandon`	La misma autorización (pagador y nonce) aparecía con contenido diferente
`payment_not_settleable`	409	`wait_and_retry`	La cita ya no es válida, pero tu autorización aún puede ejecutarse. Espera hasta `authorization_expires_at` antes de firmar uno nuevo
`payment_under_review`	409	`human_required`	Nuestro personal está revisando el pago.
`quote_bound_to_other_wallet`	409	`resign`	Otra cartera ya ha utilizado esta cita. En la respuesta hay una nueva cita.
`quote_payment_in_progress`	409	`wait_and_retry`	Se está tramitando otro pago correspondiente a este presupuesto.
`quote_config_mismatch`	409	`abandon`	El texto de la solicitud de pago no coincide con el presupuesto, o bien una repetición de una autorización de pago conlleva otra solicitud
`idempotency_key_conflict`	409	`abandon`	Tu monedero ya ha utilizado esto `idempotency_key` por otro pago en las últimas 24 horas
`rate_limited`	429	`wait_and_retry`	Se ha superado un límite (Límites)
`settlement_retry`	503	`retry_same_payment`	El pago aún se está tramitando. Vuelve a enviar la misma solicitud en `retry_after_seconds`
`channel_paused`	503	`wait_and_retry`	El servicio no acepta nuevos pagos de forma temporal.
`dependency_unavailable`	503	`wait_and_retry`	Un fallo temporal: el precio, el catálogo, la comprobación del pago u otro servicio no están disponibles.
`internal_error`	500	`wait_and_retry`	Error inesperado

Un método HTTP incorrecto devuelve 405 con el código invalid_request.

Cada respuesta del servicio contiene el X-Request-Id encabezado. Facilítalo al servicio de asistencia cuando informes de un problema.

Cuerpo del error

Reintentar acciones

Códigos de error

On this page