Errores

El error incluye un código estable y un mensaje en español. Decide con error.code, no comparando el texto del mensaje.

Forma de una respuesta de error

{
  "error": {
    "type": "validation",
    "code": "validation_failed",
    "message": "Solicitud inválida",
    "param": "email",
    "requestId": "req_ejemplo"
  }
}

param identifica el campo cuando aplica. Un recurso inexistente responde 404 con type: "not_found" y el código <recurso>_not_found, como customer_not_found, member_not_found, plan_not_found o subscription_not_found; en rutas anidadas el código nombra el recurso que falta. Conserva requestId para soporte sin registrar cuerpos, claves ni datos del cliente.

Situación	Qué hacer
Autenticación o permisos	Revisa la clave, su entorno y la habilitación del negocio
Validación	Corrige el campo señalado antes de repetir
Recurso no encontrado	Comprueba el ID y el entorno
Conflicto	Consulta el estado actual del recurso
HTTP 429	Respeta `Retry-After` cuando esté presente
Error de red o HTTP 5xx	Reintenta con espera y la misma clave de idempotencia

Catálogo de códigos

Todos los code que puede responder la API, en /v1 y en /v1/client. En TypeScript son el tipo ApiErrorCode (BilleteError.code en el SDK, que suma network_error e invalid_response). Un código nuevo llega solo con una versión nueva de la API.

Código	Qué significa
`account_not_found`	No existe el negocio.
`account_suspended`	Este negocio no está recibiendo pagos: está pausado o suspendido, o tiene un reembolso vencido.
`address_required`	Falta la dirección que pide el checkout.
`amount_required`	El producto sin variantes necesita un precio.
`amount_too_large`	El importe total supera el máximo permitido.
`api_key_expired`	Esta clave API venció.
`api_key_invalid`	La clave API no es válida.
`api_key_missing`	Falta la cabecera Authorization con tu clave secreta (Bearer).
`api_version_invalid`	Esa versión de la API no existe; usa una versión vigente.
`api_version_missing`	Falta la cabecera Billete-Version con la versión de la API de tu integración.
`api_version_retired`	Esa versión de la API ya se retiró; elige una vigente.
`approval_not_open`	Esta solicitud ya terminó.
`approval_not_pending`	Esta solicitud ya no espera una decisión.
`approval_own_request`	Otra persona debe aprobar o rechazar tu solicitud; tú puedes cancelarla.
`approval_request_not_found`	No existe la solicitud de aprobación.
`auto_charge_off`	Esta suscripción no se cobra automáticamente.
`billing_cycle_unavailable`	Este ciclo de pago no está disponible.
`business_type_required`	Elige primero el tipo de organización.
`carrier_office_unavailable`	Esa oficina ya no recibe envíos; elige otra.
`checkout_completed`	Este checkout ya fue pagado.
`checkout_expired`	Este checkout venció.
`checkout_not_editable`	Este checkout no se puede modificar.
`checkout_not_found`	No existe el checkout.
`checkout_not_open`	Solo se pueden vencer checkouts abiertos.
`checkout_selection_locked`	El producto o la variante fue eliminado. Puedes completar el pago con la selección actual, pero no modificarla.
`claim_already_open`	Ya tienes un reclamo abierto por este pago: síguelo desde el enlace que te enviamos por correo.
`claim_closed`	Este reclamo ya está cerrado.
`claim_limit_reached`	Ya no puedes abrir más reclamos por este pago: escribe directamente al negocio.
`claim_messages_limit`	Este reclamo ya tiene demasiados mensajes: es momento de resolverlo.
`claim_not_found`	No existe el reclamo.
`coupon_already_used`	Ya usaste este cupón.
`coupon_currency_mismatch`	El cupón solo aplica a precios en otra moneda.
`coupon_deleted`	Este cupón fue eliminado y no puede modificarse.
`coupon_exhausted`	El cupón alcanzó su límite de usos.
`coupon_exists`	Ya existe un cupón con ese código.
`coupon_expired`	El cupón venció.
`coupon_first_purchase_only`	Este cupón es solo para tu primera compra.
`coupon_inactive`	El cupón está desactivado.
`coupon_minimum_not_met`	El pedido no llega a la compra mínima del cupón.
`coupon_not_applicable`	Un cupón no aplica a puestos agregados a mitad del periodo.
`coupon_not_found`	No existe el cupón.
`coupons_not_allowed`	Este negocio no acepta cupones de sus clientes.
`currency_mismatch`	Todos los productos deben usar la misma moneda.
`custom_field_invalid`	El valor de un campo personalizado no es válido; `param` dice cuál.
`custom_field_required`	Falta un campo personalizado obligatorio; `param` dice cuál.
`customer_changed`	El cliente cambió durante la operación; vuelve a intentarlo.
`customer_exists`	Ya existe un cliente con este externalId.
`customer_not_found`	No existe el cliente.
`customer_session_invalid`	La sesión no es válida o venció.
`customer_session_missing`	Falta la cabecera Authorization con el token de la sesión del cliente (Bearer).
`delivery_proofs_limit`	La entrega ya tiene el máximo de fotos.
`email_required`	El correo es obligatorio.
`entity_not_applicable`	Elige primero un tipo de organización con RIF propio.
`event_not_found`	No existe el evento.
`exchange_rate_changed`	El `amount` enviado ya no es el que se cobra (venció la tasa BCV congelada o cambió el total): consulta de nuevo los métodos y muestra el nuevo monto.
`exchange_rate_unavailable`	No hay una tasa oficial vigente para ese par de monedas; inténtalo en unos minutos.
`fallback_plan_nested`	Un plan usado como respaldo no puede tener otro respaldo.
`fallback_plan_not_free`	El respaldo debe ser un plan gratuito activo, en la misma moneda y sin respaldo propio.
`feature_deleted`	Esta cuota fue eliminada y no puede modificarse.
`feature_exists`	Ya existe una cuota con esa clave.
`feature_in_use`	Algún plan incluye esta cuota o hay consumos reservados en ella: quítala de sus planes antes de eliminarla.
`feature_not_found`	No existe la cuota.
`feature_not_metered`	Esa cuota no registra uso: solo las de consumo y de cantidad lo hacen.
`feature_operation_not_allowed`	Solo las cuotas de consumo permiten operaciones.
`feature_per_not_applicable`	Solo las cuotas de consumo y de cantidad se cuentan por miembro.
`feature_release_requires_operation`	Devuelve el consumo mediante su operación original.
`feature_reset_not_applicable`	Solo las cuotas de consumo se reinician.
`feature_set_not_allowed`	Solo las cuotas de cantidad permiten fijar su uso.
`feature_value_invalid`	El valor de una cuota no es válido para su tipo.
`file_empty`	El archivo está vacío.
`file_not_found`	No existe el archivo.
`file_too_large`	Cada archivo puede pesar hasta 10 MB.
`file_type_not_allowed`	El tipo de archivo no está permitido.
`fulfillment_closed`	Ya no se puede reportar un problema con esta entrega.
`fulfillment_method_unavailable`	Este negocio no ofrece esa forma de entrega.
`fulfillment_methods_conflict`	Los productos no comparten ninguna forma de entrega.
`fulfillment_not_found`	No existe la entrega.
`fulfillment_not_offered`	Esta compra no necesita entrega.
`fulfillment_not_pending`	Solo puedes marcar como entregada una entrega por entregar.
`fulfillment_not_shipping`	Esta entrega no va por agencia.
`fulfillment_required`	Elige cómo quieres recibir tu compra.
`fulfillment_shipped_by_carrier`	Un envío se entrega en la oficina de la agencia: agrega su número de guía.
`handover_code_invalid`	Este código QR no es el de esta compra.
`idempotency_conflict`	Repite la solicitud.
`idempotency_key_invalid`	Idempotency-Key debe tener entre 8 y 255 caracteres ASCII imprimibles.
`idempotency_key_reused`	Este Idempotency-Key ya se usó con una solicitud distinta.
`idempotency_request_in_progress`	Todavía estamos procesando una solicitud con este Idempotency-Key.
`insufficient_stock`	No hay suficientes unidades disponibles de un producto.
`internal_error`	Ocurrió un error interno; inténtalo de nuevo.
`invalid_cursor`	El cursor no es válido para este orden.
`invalid_default_variant`	Elige una sola variante principal activa.
`invalid_json`	El cuerpo debe ser JSON válido.
`invalid_payment_details`	Un dato del método de pago no es válido; `param` dice cuál.
`invalid_reference`	Uno de los recursos indicados no existe.
`invalid_sort`	Esta lista no se puede ordenar así.
`invalid_token`	Este enlace no es válido.
`inventory_in_use`	Hay unidades retenidas por pagos en verificación; espera a que terminen antes de cambiar su control de stock.
`invoice_closed`	Este cobro ya no se puede pagar.
`invoice_not_closable`	Solo se pueden marcar como incobrables cobros abiertos sin un pago en verificación.
`invoice_not_found`	No existe el cobro.
`invoice_not_open`	Solo se reenvían cobros abiertos.
`invoice_not_voidable`	Solo se pueden anular cobros abiertos sin un pago en verificación.
`invoice_paid`	Este cobro ya fue pagado.
`invoice_resend_limit`	Puedes reenviar un cobro hasta cinco veces por hora. Inténtalo más tarde.
`lookup_key_in_use`	Ya tienes otro plan o producto con esa clave (lookupKey).
`max_redemptions_below_redemptions`	El máximo de usos no puede ser menor que los usos que ya tiene el cupón.
`member_not_found`	No existe el miembro.
`member_over_limit`	Este miembro supera los puestos del plan.
`member_recently_changed`	Quien se une al negocio o cambia de rol espera 48 horas para las acciones sensibles.
`member_removed`	Este miembro fue quitado.
`member_required`	Indica el miembro para consultar esta cuota.
`method_required`	Elige un método de pago.
`name_required`	Nombre: este campo es obligatorio.
`notification_not_found`	No existe la notificación.
`notification_preference_forbidden`	No puedes cambiar esta notificación.
`onboarding_already_submitted`	La verificación ya fue enviada.
`onboarding_incomplete`	Completa todos los datos requeridos antes de enviar.
`onboarding_locked`	Los datos del negocio ya fueron enviados a revisión; contacta a soporte para cambiarlos.
`onboarding_not_submitted`	El negocio todavía no envió su verificación.
`operation_amount_exceeded`	No puedes confirmar más de lo reservado.
`operation_expired`	La reserva venció y su capacidad fue devuelta.
`operation_invalid_state`	La operación ya no está reservada.
`operation_key_reused`	Esta clave de operación ya se usó con otros datos.
`operation_not_found`	No existe la operación.
`parameter_missing`	Falta un parámetro en la ruta.
`payload_too_large`	El cuerpo de la solicitud supera 1 MB.
`payment_code_in_progress`	Estamos verificando el código; espera unos segundos.
`payment_code_invalid`	El código o la referencia no es válido o venció.
`payment_code_not_expected`	Este pago no está esperando un código.
`payment_code_not_sent`	No pudimos enviar otro código.
`payment_in_progress`	Espera a que termine el pago antes de cambiar la selección.
`payment_link_deleted`	Este enlace fue eliminado y no puede modificarse.
`payment_link_not_found`	No existe el enlace de pago.
`payment_link_unavailable`	Este enlace de pago ya no está disponible.
`payment_method_unavailable`	Este negocio no ofrece ese método para este pago: no existe, no cobra en esa moneda, solo funciona en pruebas o el negocio no lo tiene.
`payment_not_claimable`	Solo puedes abrir un reclamo por un pago confirmado.
`payment_not_found`	No existe el pago.
`payment_not_refundable`	Solo se pueden reembolsar pagos confirmados.
`payments_unavailable`	Nada puede cobrar ese método ahora: su proveedor no responde o está en mantenimiento. Inténtalo de nuevo en unos minutos.
`payout_account_change_pending`	Ya hay un cambio de la cuenta de retiro pendiente: cancélalo antes de pedir otro.
`payout_not_found`	No existe el retiro.
`phone_required`	Teléfono: este campo es obligatorio.
`plan_deleted`	Este plan fue eliminado y no puede modificarse.
`plan_in_use`	El plan tiene suscripciones en curso o es el respaldo de otro plan: desactívalo para no aceptar nuevas.
`plan_inactive`	El plan está desactivado.
`plan_not_found`	No existe el plan.
`plan_seats_locked`	No puedes cambiar la forma de cobro de un plan con suscripciones.
`portal_action_disabled`	El negocio no permite hacer este cambio desde el portal.
`portal_session_invalid`	Este enlace ya se abrió o venció.
`product_deleted`	Este producto fue eliminado.
`product_inactive`	Este producto está desactivado.
`product_not_found`	No existe el producto.
`product_unavailable`	Uno de los productos ya no existe.
`production_already_enabled`	El negocio ya opera en producción.
`production_not_enabled`	Completa la activación del negocio para usar producción.
`provider_not_found`	No existe el proveedor.
`quantity_decrease_requires_renewal`	Programa la reducción de puestos para la renovación.
`quantity_limit_exceeded`	La cantidad supera el máximo por compra.
`quantity_not_adjustable`	Este plan no se cobra por puesto.
`quantity_not_allowed`	Este plan no se cobra por puesto.
`quantity_out_of_range`	La cantidad está fuera del mínimo y el máximo de puestos del plan.
`rate_limited`	Demasiadas solicitudes seguidas; espera un momento e inténtalo de nuevo.
`receipt_not_found`	No existe el recibo.
`receipt_resend_limit`	Puedes enviar el recibo hasta cinco veces por hora. Inténtalo más tarde.
`refund_amount_mismatch`	Registra el importe completo de la devolución pendiente.
`refund_approval_pending`	Este pago ya tiene un reembolso esperando aprobación.
`refund_destination_not_needed`	Esta compra no tiene una devolución esperando tus datos.
`refund_exceeds_payment`	El reembolso supera lo que queda por reembolsar del pago.
`refund_threshold_change_pending`	Ya hay un cambio de la aprobación de reembolsos pendiente: cancélalo antes de pedir otro.
`renewal_invoice`	El cobro es la renovación de una suscripción y no se puede cerrar a mano.
`representative_not_found`	No existe el representante.
`representatives_limit`	Se alcanzó el máximo de representantes.
`request_log_not_found`	No existe el registro.
`resource_conflict`	Ya existe un recurso con estos datos únicos.
`role_admin_required`	Solo propietarios y administradores.
`route_not_found`	Este endpoint no existe.
`saved_payer_not_found`	No existe el método de pago guardado.
`seat_limit_reached`	No quedan puestos disponibles en el plan.
`seats_in_use`	El cambio deja menos puestos que miembros activos: quita miembros o acepta deshabilitarlos (disableExcessMembers).
`subscription_change_in_progress`	Estamos verificando el pago de un cambio de esta suscripción.
`subscription_ended`	La suscripción ya terminó o se canceló.
`subscription_exists`	El cliente ya tiene una suscripción en curso a este plan.
`subscription_not_canceling`	Esta suscripción no tiene una cancelación programada.
`subscription_not_found`	No existe la suscripción.
`subscription_renewal_open`	Paga la renovación o programa el cambio para el próximo periodo.
`subscription_suspended`	La suscripción está suspendida: paga su renovación para reactivarla o cancélala.
`suspension_with_fallback`	Un plan con suspensión no tiene plan de respaldo: elige uno de los dos.
`tax_behavior_mismatch`	Todos los productos deben tratar los impuestos igual.
`tax_id_prefix`	El RIF no corresponde al tipo de organización.
`too_many_attempts`	Demasiados intentos de pago para este checkout.
`tracking_deadline_passed`	El plazo para agregar la guía ya terminó.
`tracking_number_in_use`	Esa guía ya pertenece al envío de otro cliente.
`tracking_verifying`	Estamos verificando la guía que agregaste.
`trial_not_applicable`	Un plan gratuito no necesita prueba.
`trial_required`	Las suscripciones creadas por API empiezan con prueba gratis; vende planes pagos con un checkout.
`trial_unavailable`	Este cliente ya usó la prueba gratis; el checkout ahora cobra el primer periodo.
`unsubscribe_invalid`	El enlace no es válido.
`unused_credit_not_accepted`	Este cambio pierde crédito no utilizado; acéptalo expresamente o prográmalo para la renovación.
`validation_failed`	El cuerpo o la consulta no cumple el esquema; `param` dice qué campo.
`variant_deleted`	Esta variante fue eliminada y no puede modificarse.
`variant_deletion_required`	Elimina la variante explícitamente antes de quitarla del producto.
`variant_not_found`	No existe la variante.
`variant_pricing_required`	Con variantes, el precio y el stock se configuran por variante.
`variant_required`	El producto tiene variantes: elige una.
`webhook_delivery_in_progress`	Este envío está en curso; podrás reenviarlo cuando termine.
`webhook_delivery_not_found`	No existe el envío.
`webhook_endpoint_deleted`	Este webhook fue eliminado y no puede modificarse.
`webhook_endpoint_disabled`	Este webhook está desactivado: actívalo para enviarle eventos.
`webhook_endpoint_not_found`	No existe el webhook.
`webhook_signature_invalid`	La firma del evento no es válida.
`webhook_url_credentials_forbidden`	La URL del webhook no puede incluir credenciales.
`webhook_url_https_required`	La URL del webhook debe usar HTTPS.
`webhook_url_invalid`	La URL del webhook no es válida.
`webhook_url_private`	La URL del webhook no puede apuntar a localhost.
`webhook_url_protocol`	La URL del webhook debe usar HTTP o HTTPS.
`webhook_url_unresolvable`	No pudimos resolver el dominio del webhook.

Registros en el dashboard

En Desarrolladores → Registros ves las solicitudes de los últimos 30 días a /v1 y las que hacen los navegadores de tus clientes en /v1/client (pagos, códigos y cambios del portal; no sus consultas), en el entorno que tengas abierto. Cada una muestra su estado, la ruta, la clave que la hizo, la versión de la API, su Idempotency-Key, la duración y lo que enviaste y respondimos. Filtra por estado (2xx, 4xx, 5xx), método y fecha, o busca por requestId, por el ID de un recurso o por parte de la ruta. El detalle de una transacción también lista las solicitudes que la tocaron.

Los cuerpos se guardan sin secretos ni datos personales: claves, tokens, correos, teléfonos, cédulas y RIF, cuentas bancarias, números de tarjeta, direcciones y nombres de personas se reemplazan por [REDACTED], igual que cualquier serie de seis dígitos o más. Un cuerpo de más de 64 KB, como una lista larga, no se guarda. Las solicitudes con una clave inexistente no se registran; las de una clave vencida o de un negocio suspendido o sin producción habilitada sí, para que veas por qué se rechazaron. Los ven propietarios, administradores y desarrolladores del negocio.

Errores

ErroresCopiar enlace

Catálogo de códigosCopiar enlace

Registros en el dashboardCopiar enlace

En esta página

Errores

Catálogo de códigos

Registros en el dashboard