Códigos de error de facturación
Qué significan los errores al facturar y cobrar: los motivos de rechazo del banco que ves en pantalla y los códigos que devuelve la API a tus integraciones.
Actualizado el . 7 min de lectura
Incluido en todos los planes. Ver precios
Esta página reúne los errores que pueden aparecer al facturar y al cobrar. La primera parte explica los motivos de rechazo de un cobro con tarjeta, que verás en la ficha de la factura. El resto es una referencia para quien conecta una aplicación externa a UTILIA OS: los códigos estables (errorCode) que devuelve la API.
Por qué el banco rechaza un cobro
Cuando un cobro con tarjeta falla, la ficha de la factura lo muestra en Últimos intentos con un motivo en castellano. Estos son los más habituales:
| Motivo que ves | Código de Stripe |
|---|---|
| Tu banco rechazó el cobro. | card_declined |
| Fondos insuficientes. | insufficient_funds |
| La tarjeta está caducada. | expired_card |
| El código CVC no es correcto. | incorrect_cvc, invalid_cvc |
| El número de la tarjeta no es correcto. | incorrect_number, invalid_number |
| El banco solicitó autenticación adicional. | authentication_required |
| Hubo un problema temporal procesando el cobro. Inténtalo más tarde. | processing_error, try_again_later |
| El banco bloqueó la tarjeta. | lost_card, stolen_card, pickup_card |
| El cobro fue bloqueado por seguridad. | fraudulent, merchant_blacklist |
| La tarjeta no admite la divisa de la factura. | currency_not_supported |
| La tarjeta no admite este tipo de pago. | card_not_supported |
Cualquier código que no esté en la lista se muestra como «El cobro no se pudo completar.».
¿Reintentar o pedir otra tarjeta?
El problema es pasajero
Reintenta más tarde
La tarjeta no sirve
Pide otra tarjeta
Hay un dato mal o falta su confirmación
Pide al cliente que lo revise
Cómo devuelve la API los errores
Los endpoints de facturación y cobro devuelven el error con este formato:
{
"statusCode": 403,
"errorCode": "BILLING_NOT_ENABLED",
"message": "La facturación no está habilitada en esta aplicación.",
"requestId": "req_01HXYZ..."
}El errorCode es estable entre versiones; el message puede cambiar para mejorar la redacción. Un mismo errorCode puede llegar con estados HTTP distintos según la causa, así que tu integración debe decidir siempre por el errorCode, nunca por el estado.
Configuración y plan
| Código | Estado | Qué significa |
|---|---|---|
BILLING_NOT_ENABLED | 403 | La aplicación externa no tiene activada la facturación. Se activa en su panel. |
MODULE_NOT_ENABLED | 403 | El plan de la organización no incluye el aplicativo que gobierna la operación. En cobros, devoluciones con tarjeta y tarjetas guardadas, es Pagos con tarjeta (Stripe). Se resuelve contratándolo, no cambiando permisos: ningún rol se salta esta comprobación. |
STRIPE_ACCOUNT_NOT_READY | 409, 400 o 503 | La organización no puede cobrar con tarjeta: no hay cuenta de Stripe conectada o no tiene los cobros habilitados (409), falló el guardado de la tarjeta (400) o la pasarela no está disponible (503). Revisa Finanzas › Ajustes › Pagos con tarjeta (Stripe), necesitas entrar con tu cuenta. |
STRIPE_NOT_CONFIGURED | 503 | La pasarela de pagos con tarjeta no está activada en UTILIA OS. No depende de tu organización: es un estado declarado, no una avería, así que no lo reintentes en bucle. |
STRIPE_DISCONNECT_UNAVAILABLE | 409 | UTILIA OS no pudo retirar su acceso a la cuenta de Stripe. La cuenta sigue conectada y operativa. Retira el acceso desde el panel de Stripe, en Ajustes › Aplicaciones conectadas; la respuesta incluye stripeConnectedAppsUrl con el enlace. |
No confundas el 503 de la plataforma con el 403 del plan
503 · Toda la plataforma
STRIPE_NOT_CONFIGURED
403 · Solo tu organización
MODULE_NOT_ENABLED
El endpoint PATCH /finance/stripe/account/publishable-key está retirado: responde siempre 410 con ENDPOINT_RETIRED y no tiene sustituto, porque la clave publicable que se usa es la de la plataforma.
Validación de facturas
| Código | Estado | Qué significa |
|---|---|---|
VALIDATION_ERROR | 400 | Algún campo no cumple las validaciones. El campo details suele traer la lista. |
BILLING_AMOUNT_EXCEEDS_LIMIT | 403 | El total supera el tope billingMaxAmountCents configurado para la aplicación. |
INVOICE_NOT_FOUND | 404 | La factura no existe o la emitió otra aplicación. |
INVOICE_NOT_ACCESSIBLE | 404 | El usuario externo indicado no es el dueño de la factura. |
INVOICE_STATE_INVALID | 400 | La factura está en un estado que no admite la operación (por ejemplo, cobrar un borrador o una factura sin importe pendiente). |
INVOICE_ALREADY_CANCELLED | 400 | La factura ya está anulada. |
INVOICE_ALREADY_PAID | 400 | La factura ya está pagada. Suele ocurrir cuando conviven un cobro manual y uno automático sobre la misma factura. |
INVOICE_TAX_COHERENCE_ISSUES | 400 | Los impuestos de las líneas no son coherentes con el sistema fiscal de la organización (IGIC en península, IVA en Canarias, tipo vacío o que no pertenece al sistema). La factura no se crea ni se emite. La respuesta trae taxSystem, suggestedSystem e issues[] con el detalle por línea: lineIndex, code (NULL_TAX_TYPE, INCOHERENT_WITH_SYSTEM, RATE_NOT_IN_SYSTEM o LEGACY_HEADER_RATE_MISMATCH), message, suggestedTaxType, currentTaxType y currentTaxRate. |
Rectificativas y notas de crédito
Las reglas que hay detrás de estos códigos están en Rectificativas y notas de crédito.
| Código | Estado | Qué significa |
|---|---|---|
RECTIFICATION_SUBSTITUTION_ALREADY_EXISTS | 409 | Ya existe una rectificativa por sustitución emitida de esa factura. |
RECTIFICATION_HISTORY_REVIEW_REQUIRED | 409 | Las rectificaciones anteriores de la factura no permiten calcular un saldo único (por ejemplo, se pide una sustitución sobre una factura que ya tiene rectificaciones). Hay que revisarlas antes de continuar. |
RECTIFICATION_DIFFERENCE_BELOW_ZERO | 400 | La rectificación por diferencias dejaría la factura, o alguno de sus tramos fiscales, por debajo de cero. |
RECTIFICATION_AMOUNTS_INVALID | 400 | Una sustitución tiene importes negativos: debe expresar la factura corregida completa con importes no negativos. |
CREDIT_NOTE_SUBSTITUTION_UNSUPPORTED | 400 | Se pidió una nota de crédito por sustitución. Las notas de crédito son siempre por diferencias; para sustituir, crea una factura rectificativa. |
RECTIFICATION_LEGAL_METADATA_REQUIRED | 400 | Falta el código legal o no vale para la factura original (una factura simplificada solo admite R5). |
RECTIFICATION_RECIPIENT_BELONGS_TO_OTHER_CLIENT | 400 | El NIF indicado pertenece a otro cliente de la organización. Una rectificativa no puede cambiar el destinatario a otra empresa: el camino es la reemisión. La respuesta trae conflictingClientId y conflictingClientName. |
Los códigos RECTIFICATION_DIFFERENCE_EXCEEDS_REMAINING y RECTIFICATION_AMOUNT_EXCEEDS_ORIGINAL ya no se devuelven: si tu integración los esperaba, cámbialos por los de esta tabla.
Usuarios externos
| Código | Estado | Qué significa |
|---|---|---|
EXTERNAL_USER_NOT_FOUND | 404 | No hay ningún usuario externo con ese externalId en tu aplicación. Los usuarios se crean con la primera llamada a facturas o al alta de tarjeta. Un usuario de otra aplicación tampoco se encuentra. |
Métodos de pago
| Código | Estado | Qué significa |
|---|---|---|
PAYMENT_METHOD_NOT_FOUND | 404 | El método de pago no existe o no es de ese usuario. Es también la respuesta si intentas usar la tarjeta de otro usuario: se devuelve 404 y no 403, para no revelar que existe. |
PAYMENT_METHOD_INACTIVE | 400 | La tarjeta está desvinculada o caducada. |
PAYMENT_METHOD_ACTIVE_INTENT | 409 | Ya hay un alta o un cobro en curso con ese método de pago. Espera a que termine. |
Los rechazos del banco no llegan con un errorCode propio de UTILIA OS: el cobro queda registrado como intento fallido, con el código de Stripe tal cual (card_declined, insufficient_funds…) en su campo errorCode y la traducción en errorMessage. No existen códigos con prefijo STRIPE_ del tipo STRIPE_CARD_DECLINED.
Autenticación de la API externa
La API externa se autentica con la cabecera X-Api-Key.
| Código | Estado | Qué significa |
|---|---|---|
API_KEY_REQUIRED | 401 | Falta la cabecera X-Api-Key. |
API_KEY_INVALID | 401 | La clave no es válida o se revocó. |
API_KEY_NOT_LINKED | 401 | La clave es válida, pero no está asociada a ninguna aplicación externa. |
APP_DISABLED | 403 | La aplicación externa está desactivada. |
ORIGIN_NOT_ALLOWED | 403 | El origen de la petición no está entre los orígenes permitidos de la aplicación. |
RATE_LIMIT_EXCEEDED | 429 | Se superó el límite de peticiones. La cabecera Retry-After indica cuántos segundos esperar. |
Cómo reaccionar
- Errores 4xx distintos de 429: corrige la petición (datos, permisos, estado). No la repitas igual.
- 429, 502, 503 y 504: son temporales. Reintenta con espera creciente; el SDK lo hace solo hasta tres veces.
- Cobro rechazado por el banco: informa al cliente con el motivo y pídele otra tarjeta o que hable con su banco.
- Autenticación 3D Secure pendiente: el cobro no terminó. Tu aplicación debe completar la verificación con el
clientSecretdevuelto.
Todos los errores llevan un requestId. Si necesitas ayuda con un error concreto, facilítaselo al equipo de soporte de UTILIA: con él localizan la petición y, si fue un rechazo de Stripe, el intento correspondiente.
Más información
- Endpoints de facturas: formato de cada endpoint.
- Errores, identificador de petición y reintentos: el comportamiento común de los errores de la API.