Los códigos de estado HTTP envejecen despacio. 200 y 404 significan lo mismo desde hace décadas y el registro es tan estable que los desarrolladores dejan de pensar en él. Y luego está 402.

402 Payment Required aparece en las especificaciones HTTP desde 1997, marcado como reservado para uso futuro, y durante casi todo ese tiempo nadie lo usó. En 2025 eso cambió por dos lados a la vez: Cloudflare empezó a devolver 402 para cobrar a los rastreadores de IA por el contenido, y el estándar x402 construyó un protocolo completo de pagos entre máquinas sobre el mismo código.

01Por qué HTTP 402 estuvo sin uso 25 años

La especificación original de HTTP/1.1 reservó 402 sin definir un cuerpo. Un código de estado sin formato acordado es un código que ningún cliente puede ejecutar: un navegador no puede saber adónde enviar dinero y un proxy no puede saber si debe reintentar.

Ese hueco importó menos de lo que parece, porque los pagos en línea crecieron fuera de HTTP. Páginas de pago, formularios de tarjeta, redirecciones a un proveedor y webhooks viven por encima del protocolo. La petición que llega a tu API ya está pagada; lo que faltaba era una forma de cobrar a máquinas que hablan directamente con una API sin página de pago.

402 es un código estándar, no un truco.

Tanto pay-per-crawl como x402 mantienen la semántica HTTP: el recurso existe, el cliente se entiende y el servidor simplemente se niega a entregar contenido hasta que se liquide el pago.

02Cómo x402 convierte 402 en un apretón de manos de pago

x402 es un estándar abierto, publicado bajo Apache-2.0, para cobrar por llamadas a API y contenido directamente sobre HTTP. No tiene cuentas, sesiones ni gestión de credenciales: la instrucción de pago viaja en las cabeceras de la respuesta.

El flujo documentado tiene cinco pasos:

1. El cliente pide un recurso, por ejemplo GET /weather.
2. Si hace falta pagar, el servidor responde 402 Payment Required con las instrucciones de pago.
3. El cliente prepara el pago y reintenta la petición.
4. El servidor verifica y liquida el pago, por sí mismo o mediante un facilitator de x402.
5. Cuando el pago es válido, el servidor entrega el recurso.

En las cabeceras v2 documentadas de x402, ese intercambio usa tres nombres:

Cada valor es un JSON codificado en Base64, lo que evita problemas con los caracteres permitidos en cabeceras y lo mantiene legible para cualquier cliente HTTP.

# Primera petición: sin pago, el servidor responde 402
curl -i https://api.example.com/weather

# Lo que devuelve
HTTP/1.1 402 Payment Required
PAYMENT-REQUIRED: eyJhY2NlcHRzIjpbXX0=
content-length: 0

La decisión de diseño importante es que el pago ocurre dentro del ciclo normal de la petición. La URL no cambia, no hay redirección a una pasarela alojada y un agente autónomo puede completar todo el intercambio sin intervención humana.

03Qué devuelve realmente pay-per-crawl de Cloudflare

pay-per-crawl, presentado por Cloudflare en julio de 2025, aplica el mismo código a otro problema: los dueños de contenido que quieren cobrar cuando un rastreador de IA lee su sitio.

El comportamiento publicado es directo. Cada petición de un rastreador recibe uno de tres resultados que elige el editor: permitir gratis, cobrar un precio único para todo el dominio o bloquear por completo. Cuando la decisión es cobrar y la petición no incluye pago, Cloudflare devuelve 402 Payment Required con la cabecera crawler-price indicando el precio.

Dos detalles lo separan de un paywall común:

• Cloudflare actúa como merchant of record, así que el editor no cobra micropagos uno por uno.
• Los rastreadores se identifican con peticiones firmadas mediante Web Bot Auth, de modo que un cliente cualquiera no puede hacerse pasar por un rastreador para negociar precio.

Dicho de otro modo, aquí 402 sirve para anunciar un precio a una máquina que quizá tenga relación de facturación con el operador en el futuro. Es un trabajo muy distinto del paywall para navegadores que resuelven 401 y 403.

04Qué debería incluir una respuesta 402

Como la especificación original nunca definió un cuerpo, cada implementación inventa sus detalles. Si añades 402 a una API, incluye lo necesario para que un cliente actúe sin adivinar:

• Precio y unidad. Por petición, por mil peticiones o por rastreo: dilo explícitamente.
• Dónde y cómo pagar. Un endpoint de pago, una red y una dirección de destino, o el nombre de un esquema.
• Cómo probar el pago. La cabecera que el cliente debe enviar al reintentar y su formato exacto.
• Cuánto dura la oferta. Un precio sin caducidad no se puede cachear con seguridad.
• Un cuerpo legible por máquina. JSON es más fácil para un agente que la prosa y sigue siendo útil para una persona.

{
  "error": "payment_required",
  "price": { "amount": "0.002", "currency": "USDC", "per": "request" },
  "accepts": ["exact"],
  "retry_header": "PAYMENT-SIGNATURE",
  "expires_in": 300
}

05402 frente a 401, 403 y 429

Los endpoints de pago son tan nuevos que los equipos eligen el código equivocado. Los cuatro candidatos se separan fácil si nombras lo que falta.

Dos reglas lo mantienen limpio. No devuelvas 402 a una persona que simplemente no ha iniciado sesión: eso es 401. Y no devuelvas 402 por un límite de tasa que se resuelve esperando, porque Retry-After en un 429 ya lo expresa.

402 le dice al cliente que pague, no que reintente a ciegas.

Si tu API devuelve 402 sin instrucciones, los clientes correctos lo tratarán como un 4xx genérico y se detendrán. El valor está en las cabeceras y el cuerpo, no solo en el número.

06Implementar 402 sin romper clientes

Añadir un código de estado es una decisión de compatibilidad, así que trátala como tal:

1. Reserva el código para clientes máquina. Para tráfico de navegador, redirige a una página de pago o responde 401 con un mensaje claro; los 4xx desconocidos confunden más de lo que ayudan.
2. El primer 402 no debe costar nada. Nunca cobres ni consumas cuota en la petición que lleva el precio; si no, un ciclo de reintentos puede facturar contenido que el cliente nunca recibió.
3. Haz idempotente el reintento. Un cliente que paga y reintenta no debe pagar dos veces si el primer reintento se pierde en la red.
4. Registra 402 aparte de los errores 4xx. Un endpoint de pago que responde 402 está sano; un 404 no. Si ambos cuentan como «error del cliente» en el mismo panel, la señal desaparece.
5. Publica el contrato de cabeceras. Un agente no puede adivinar PAYMENT-SIGNATURE, PAYMENT-REQUIRED ni crawler-price; sin documentación no se conectará nada.

07Qué significa para editores y dueños de APIs

Por primera vez en dos décadas, el código menos usado del registro tiene trabajo. Es un trabajo concreto: marcar el punto donde una petición HTTP se convierte en una transacción y permitir que una máquina la complete sin nadie en medio.

Ya sea que operes una API de pago o veas a los rastreadores de IA leer tu contenido, el paso práctico es el mismo. Revisa qué devuelve hoy tu servidor, decide qué debe hacer el cliente con cada código y asegúrate de que la respuesta le diga qué hacer después.