Errores

Qopper devuelve errores en JSON junto con un código de estado HTTP:

{ "error": "Saldo insuficiente. Disponible: $56 USDC" }

Códigos de estado

Estado	Significado	Causa típica
`400`	Petición mal formada	Campo ausente o inválido (`amountUsdCents` que no es un entero positivo, dirección incorrecta…).
`401`	Sin autenticar	Credencial ausente o equivocada; el mensaje dice cuál se esperaba.
`402`	Pago requerido / rechazado por política	Presupuesto excedido, tope por cargo, o los límites duros del agente bloquearon el pago. El cuerpo explica exactamente por qué.
`403`	Prohibido	Credencial válida con el alcance equivocado (por ejemplo, el recurso de otro comercio) o dirección bloqueada por KYT.
`404`	No encontrado	Id desconocido de cargo, PayLink o endpoint.
`409`	Conflicto	Operación inválida para el estado actual (pagar un cargo ya pagado, PayLink caducado).
`500`	Error del servidor	Bug o problema de infraestructura. Se puede reintentar sin riesgo.
`503`	Servicio no disponible	La función requiere PostgreSQL y no está configurado; o el facilitador x402 no responde.

Los rechazos de política a veces son 200

Un matiz que conviene conocer: cuando un agente paga un cargo y su política bloquea o pausa el pago, el endpoint sigue respondiendo 200 con un resultado estructurado en vez de un código de error:

{ "paid": true, "charge": { "...": "..." } }                        // liquidado
{ "pendingApproval": true, "approvalId": "...", "reason": "..." }   // pausado para el humano
{ "error": "Categoría 'services' no está ..." }                     // bloqueado (HTTP 402)

Los agentes son programas que se ramifican según el resultado; darles un motivo legible por máquina es más útil que un código de estado a secas.

Cómo diseñar tu integración alrededor de los errores

Ramifica según los tres resultados de pago, no solo entre éxito y fallo.
Parsea los errores de presupuesto: excede_presupuesto_restante_350 lleva dentro los centavos exactos que quedan.
Reintenta solo en 5xx. Un 4xx significa que tu entrada o tu estado están mal; repetir no va a ayudar.
Registra los valores de reference de los pagos exitosos; coinciden entre los cargos del comercio y los rastros de auditoría de los agentes.

​Errores

​Códigos de estado

​Los rechazos de política a veces son 200

​Cómo diseñar tu integración alrededor de los errores

Errores

Códigos de estado

Los rechazos de política a veces son 200

Cómo diseñar tu integración alrededor de los errores