Manejar errores

Si una llamada de Payments falla, el SDK de TypeScript lanza PaymentsError y el de Python, una subclase de TimbroError. Invoices usa InvoiceError, que también incluye failure y, cuando existe, invoiceId. En cambio, un intento rechazado no es un error. El pago sigue en requires_customer_action con lastDecline, y el cliente puede intentarlo de nuevo.

Respuesta	Qué hacer
400	Corrige los campos indicados en problems.
422 en Invoices	Revisa problems y issuanceBlockers. Si no hay invoiceId, la solicitud no creó una factura; corrígela y vuelve a llamar create.
401 o 403	Revisa la clave, el negocio, el modo (Prueba o En vivo) y los permisos.
404	Revisa el identificador y la clave con la que consultas.
409	Revisa code. Puede que ya hayas usado la referencia con otros datos o que el estado del pago no permita esa acción.
429 o 503	Si recibes Retry-After, espera el tiempo indicado antes de reenviar la misma solicitud.
La solicitud no responde o devuelve 5xx	Confirma qué pasó con el pago antes de iniciar otro pago.

TypeScript

import { PaymentsError } from "@timbro/payments";

export function supportDetails(error: unknown) {
  if (!(error instanceof PaymentsError)) throw error;
  return { code: error.code, requestId: error.requestId, problems: error.problems };
}

Python

APIError y sus subclases, como InvalidRequestError o ConflictError, indican que Timbro respondió con un error. APIConnectionError indica que no llegó una respuesta, y su code dice qué significa: connection_failed si la solicitud no salió o una lectura se cortó, request_timed_out si una lectura agotó el tiempo, y outcome_unknown si una escritura pudo llegar a Timbro. En los dos primeros casos no cambió nada. El SDK de TypeScript usa transport_failure para los tres.

from timbro_payments import APIError, TimbroError


def support_details(error: TimbroError) -> dict[str, object]:
    details: dict[str, object] = {"code": error.code, "request_id": error.request_id}
    if isinstance(error, APIError):
        details["problems"] = error.problems
    return details

Para Invoices, conserva también el ID de la factura y los bloqueos que requieren intervención:

import { InvoiceError } from "@timbro/invoices";

export function invoiceSupportDetails(error: unknown) {
  if (!(error instanceof InvoiceError)) throw error;
  return {
    code: error.code,
    requestId: error.requestId,
    invoiceId: error.invoiceId,
    failure: error.failure,
    problems: error.problems,
    issuanceBlockers: error.issuanceBlockers,
  };
}

Una factura ya creada puede terminar en rejected u operatorRequired después de una solicitud exitosa. Consulta esa misma factura; para sustituir una rechazada, sigue corregir el e-CF. Si se pierde la respuesta, busca por invoiceReference o reenvía los mismos datos con esa referencia antes de emitir otro documento.

Guarda code, requestId y problems junto al identificador del pago. El equipo de Timbro puede usarlos para revisar el caso. No guardes claves, datos de tarjeta ni links completos de Checkout en tus registros de errores.

isRetryable indica que el error puede ser temporal. Antes de repetir la operación, comprueba cómo evitar duplicarla. Para crear pagos y reembolsos, reenvía los mismos datos con el mismo paymentReference o refundReference. Consulta las condiciones de las demás operaciones en la referencia REST.

En Python, retryable indica lo mismo. Si outcome_unknown es True, la operación pudo completarse aunque la llamada falló. Confirma qué pasó con el pago antes de repetirla; el texto del error indica cómo encontrar el resultado.