--- title: "Manejar errores | Timbro" description: "Qué revisar cuando una solicitud falla" canonical: "https://timbro.do/docs/produccion/errores/" --- Webhooks y errores # 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](https://timbro.do/docs/produccion/recuperar-pago-incierto/) antes de iniciar otro pago. | - [TypeScript](https://timbro.do/docs/produccion/errores/#tab-panel-0-0) - [Python](https://timbro.do/docs/produccion/errores/#tab-panel-0-1) ```ts 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 }; } ``` `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. ```python 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: ```ts 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](https://timbro.do/docs/comprobantes/corregir-ecf/). 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](https://timbro.do/docs/reference/payments/). 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](https://timbro.do/docs/produccion/recuperar-pago-incierto/) antes de repetirla; el texto del error indica cómo encontrar el resultado. [Página anterior\ Recibir notificaciones](https://timbro.do/docs/cobros/webhooks/)[Siguiente página\ Repetir la solicitud sin duplicar el pago](https://timbro.do/docs/cobros/reintentos-e-idempotencia/) Vende, atiende a tus clientes y cobra desde tu celular © 2026 Timbro. Todos los derechos reservados [Español](https://timbro.do/docs/produccion/errores/)[English](https://timbro.do/en/docs/produccion/errores/) ## Productos [Facturación](https://timbro.do/facturacion-electronica/)[Atiende](https://timbro.do/atiende/)[Cobra](https://timbro.do/pagos/)[Portal Timbro](https://timbro.do/portal-timbro/)[Integraciones](https://timbro.do/integraciones/)[Cuenta Timbro](https://timbro.do/cuenta-timbro/)[Precios](https://timbro.do/precios/) ## Desarrolladores [SDK y API](https://timbro.do/desarrolladores/)[Documentación](https://timbro.do/docs/)[Referencia de la API](https://timbro.do/docs/reference/payments/) ## Empresa [INDEXA, la empresa detrás de Timbro](https://indexa.do/)[Presentaciones](https://timbro.do/presentaciones/) ## Ayuda [Cómo empezar](https://timbro.do/como-empezar/)[Guía de facturación electrónica](https://timbro.do/guias/facturacion-electronica-republica-dominicana/)[Contacto](https://timbro.do/contacto/) ## Legal [Condiciones para negocios](https://timbro.do/politicas/negocios/)[Política de uso](https://timbro.do/politicas/uso/)[Privacidad](https://timbro.do/politicas/privacidad/)[Seguridad](https://timbro.do/politicas/seguridad/)[Todos los documentos](https://timbro.do/politicas/)