Manejo de errores y catálogo de códigos#

Todos los errores de la API son documentos application/problem+json según la RFC 9457 ↗ (se abre en una pestaña nueva), con un miembro de extensión propio: code.

{
  "type": "https://api.apipay.io/problems/amount-exceeds-refundable",
  "title": "Unprocessable Entity",
  "status": 422,
  "detail": "El monto solicitado supera el saldo reembolsable del payment intent.",
  "instance": "/v1/refunds",
  "code": "amount_exceeds_refundable"
}

Además puede traer miembros de extensión específicos del problema. Por ejemplo, un 503:

{
  "type": "https://api.apipay.io/problems/gateway-unavailable",
  "title": "Service Unavailable",
  "status": 503,
  "detail": "La pasarela webpay no esta disponible en este momento.",
  "instance": "/v1/payment-intents",
  "code": "gateway_unavailable",
  "gateway_id": "webpay",
  "retry_after_seconds": 30
}

La regla de oro#

También sirven status y type —los tres son estables—, pero code es el más preciso: distingue card_declined de gateway_rejected con el mismo 402, y idempotency_key_reuse de invalid_state_transition con el mismo 409.

El catálogo: 17 códigos#

4xx — el problema está en la petición#

5xx — el problema está de nuestro lado#

X-Request-Id: el dato que pide soporte#

Toda respuesta de la API, exitosa o no, incluye la cabecera X-Request-Id. Es el identificador con el que se correlaciona una petición concreta en las trazas de la plataforma.

Los cuatro SDKs lo exponen en cada error de la API. Regístralo siempre que loguees un fallo: sin él, un ticket de soporte que dice «un pago falló ayer por la tarde» no es investigable.

import { ApiError } from '@apipay/node';
try {
  await apipay.paymentIntents.confirm(intentId, { payment_method_token: token });
} catch (error) {
  if (error instanceof ApiError) {
    logger.error('apipay_error', {
      code: error.code,           // estable: sobre esto se ramifica
      status: error.status,
      requestId: error.requestId, // X-Request-Id, para soporte
    });
    // Cuidado con volcar error.problem entero a un logger de terceros:
    // detail puede contener texto libre de la pasarela.
  }
  throw error;
}

Errores tipados en los SDKs#

Cada code se materializa como una excepción de una clase concreta, así que puedes ramificar con el sistema de tipos en vez de comparar cadenas:

Un code que tu versión del SDK no conozca —uno añadido después de publicarla— aterriza en la clase base (ApiError en Node.js, APIError en Python, ApiException en Java y PHP) o en la que corresponda a su estado HTTP, sin romper la integración.

Capturar por familias#

import {
  ApiPayError,
  ConflictError,
  PaymentError,
  RateLimitError,
  UnprocessableError,
} from '@apipay/node';
try {
  await cobrar();
} catch (error) {
  if (error instanceof PaymentError) {
    // 402: card_declined o gateway_rejected. Rechazo, no bug.
    return mostrarRechazoAlPagador(error.code);
  }
  if (error instanceof RateLimitError) {
    // El SDK ya respeto Retry-After en los GET; aqui llega tras agotar reintentos.
    return reencolarConEspera(error.retryAfter);
  }
  if (error instanceof ConflictError) {
    // 409: idempotencia o transicion invalida. Conciliar, no reintentar.
    return conciliar();
  }
  if (error instanceof UnprocessableError) {
    // 422: regla de negocio. La peticion hay que cambiarla.
    return corregirSolicitud(error.code);
  }
  if (error instanceof ApiPayError) {
    // Raiz de todo el SDK: incluye errores locales de configuracion y de red.
    return registrarYFallar(error);
  }
  throw error;
}

Reintentos: qué hace el SDK y qué te toca a ti#

Parámetros del backoff, idénticos en los cuatro SDKs:

El tope de 60 s sobre Retry-After es una salvaguarda: un proxy o un WAF que devuelva Retry-After: 3600 dormiría tu proceso una hora.

Cabeceras de límite de tasa#

Un 429 viene acompañado de:

Errores que no vienen de la API#

No todo error del SDK es una respuesta HTTP. Hay tres familias más, y conviene distinguirlas porque la reacción correcta es distinta:

Siguientes pasos#

• Webhooks: cómo llegan los desenlaces que no ves en la respuesta HTTP.
• Modo test: cómo provocar cada código a voluntad para probar tu manejo.
• Payment intents: la matriz que genera los invalid_state_transition.
• Referencia de API: el esquema Problem y las respuestas de cada endpoint.