Manejo de errores

La API responde los errores en JSON y usa códigos de estado HTTP estándar. Para manejar errores de forma programática, usa code: es un string estable y predecible.

message está pensado para lectura humana. Hoy los mensajes de la API se devuelven en español. Pueden cambiar para mejorar claridad o soportar localización, así que no deberían usarse para branching de lógica.

Objeto de error

{
  "ok": false,
  "message": "El campo \"customer.email\" es requerido.",
  "status": 400,
  "code": "invalid_request",
  "location": "body",
  "path": "customer.email",
  "errors": [
    {
      "message": "El campo \"customer.email\" es requerido.",
      "code": "required",
      "source": "facturapi",
      "location": "body",
      "path": "customer.email"
    }
  ]
}

Campo	Tipo	Descripción
ok	boolean	Siempre es false en respuestas de error. Puedes ignorarlo para manejo programático.
message	string	Mensaje legible para humanos.
status	number	Código de estado HTTP.
code	string	Código raíz estable para manejar el error.
location	string	Ubicación del dato relacionado con el error, por ejemplo body, query, params o files. Sólo se incluye cuando aplica.
path	string	Ruta del campo relacionado con el error. Sólo se incluye cuando aplica.
errors	array	Detalles accionables para corregir la solicitud o entender una respuesta externa. Puede incluir varios elementos cuando se detectan varios problemas.
errors[].message	string	Mensaje legible de un detalle.
errors[].code	string	Subcódigo del detalle. En validaciones de Facturapi usa un subcódigo de validación de entrada o de información fiscal; en errores externos puede ser el código original del SAT o PAC.
errors[].location	string	Ubicación del dato relacionado con el detalle, por ejemplo body, query, params o files.
errors[].path	string	Ruta del campo relacionado con el detalle.
errors[].source	string	Fuente del detalle. Puede ser facturapi, sat o pac.

Cómo interpretar los códigos

El code raíz clasifica el resultado principal de la solicitud y es el valor que deberías usar primero para decidir cómo manejar el error.

El arreglo errors[] aparece cuando la respuesta necesita explicar uno o más detalles además del resultado principal: por ejemplo, varios campos inválidos en una misma solicitud o los motivos que devolvió un proveedor externo. Sus códigos son subcódigos de detalle y no reemplazan al code raíz. Cuando source es facturapi, el subcódigo y el mensaje son definidos por Facturapi. Cuando source es externo, el subcódigo puede ser el código original del sistema indicado.

Cuando el error usa su mensaje raíz por defecto, message repite el mensaje del primer detalle de errors[]. Esto conserva un mensaje útil para integraciones que todavía no procesan detalles estructurados; para lógica programática, usa siempre code, errors[].code y path.

Errores de validación

Cuando la petición no cumple el contrato de entrada, el error raíz usa code: "invalid_request". Si hay detalles, errors[] incluye cada campo inválido con source: "facturapi", path, location y un subcódigo de validación.

Los subcódigos de validación están documentados al final de esta página como subcódigos de detalle porque aparecen en errors[].code, no en el code raíz.

Errores externos

Algunas operaciones dependen de validaciones o servicios externos, como SAT o PAC. En esos casos, el code raíz sigue siendo un código de Facturapi, por ejemplo invoice_stamping_validation_error.

Si el proveedor externo devuelve detalles útiles que Facturapi no puede clasificar de forma confiable, se incluyen en errors[] con su código original:

{
  "message": "No se encontró el RFC [AAA010101AAA] en la Lista de Contribuyentes Obligados.",
  "status": 400,
  "code": "invoice_stamping_validation_error",
  "errors": [
    {
      "message": "No se encontró el RFC [AAA010101AAA] en la Lista de Contribuyentes Obligados.",
      "code": "402",
      "source": "pac"
    }
  ],
  "ok": false
}

Para códigos de validación de timbrado emitidos por el SAT, consulta la Matriz de errores CFDI 4.0 publicada dentro de la documentación oficial del Anexo 20.

Headers útiles

Algunas respuestas de error incluyen headers útiles para manejo programático u observabilidad:

Header	Descripción
Retry-After	Segundos recomendados antes de reintentar. Se incluye en errores con code: "rate_limit_exceeded".
X-Facturapi-Log-Id	ID de correlación de la solicitud. Puedes conservarlo en tu observabilidad para investigar errores con soporte.

Códigos raíz (code)

Esta lista es la referencia documentada de códigos raíz públicos de la API. Podemos agregar nuevos códigos en cualquier momento cuando nuevas funcionalidades o nuevos casos de error lo requieran, pero procuramos mantener esta página actualizada para que las integraciones tengan una referencia predecible.

CommonErrorCode

Código	Descripción
conflict	La solicitud no puede completarse por un conflicto.
forbidden	No tienes permiso para realizar esta acción.
internal_error	Ocurrió un error interno.
not_found	No se encontró el recurso solicitado.
unauthorized	No se pudo autenticar la solicitud.

AuthErrorCode

Código	Descripción
api_key_invalid	La API key proporcionada no es válida.
api_key_not_allowed	Esta API key no puede realizar esta acción.
feature_not_available	Esta funcionalidad no está disponible para tu organización.
live_api_key_required	Esta operación requiere una API key de producción.
mcp_permission_denied	No tienes permiso para usar esta herramienta.
missing_credentials	No se proporcionaron credenciales.
organization_incomplete	La organización no está configurada para realizar esta operación.
subscription_required	Esta operación requiere una suscripción activa.
subscription_live_access_required	Tu suscripción no permite usar el ambiente de producción.
user_key_invalid	La user key proporcionada no es válida.
user_suspended	El usuario está suspendido.

RequestErrorCode

Código	Descripción
idempotency_key_in_use	La idempotency key ya está siendo usada.
rate_limit_exceeded	Se excedió el límite de solicitudes.
date_range_too_large	El rango de fechas excede el límite permitido.
image_file_required	Se requiere un archivo de imagen.
invalid_country_code	El código de país no es válido.
invalid_date	La fecha no es válida.
invalid_date_range	El rango de fechas no es válido.
invalid_image_file	El archivo proporcionado no es una imagen válida.
invalid_json	El JSON enviado no es válido.
invalid_request	La solicitud no es válida.
invalid_multipart_form_data	Los datos multipart/form-data no son válidos.
invalid_state_code	El código de estado no es válido.
invalid_timezone	La zona horaria no es válida.
multipart_limit_exceeded	La solicitud multipart/form-data excede los límites permitidos.
page_too_large	La página solicitada excede el límite permitido.
payload_too_large	El payload excede el tamaño máximo permitido.

TaxInfoValidationCode

Estos códigos describen errores de información fiscal validados por Facturapi. Cuando la validación fiscal de un cliente u organización detecta un solo problema, aparece en code. Las validaciones de entrada y el endpoint de validación de información fiscal de un cliente los devuelven en errors[].code.

Código	Descripción
legal_name_mismatch	El nombre o razón social no corresponde al RFC en los registros del SAT. Verifica que coincida exactamente con la Constancia de Situación Fiscal.
tax_address_zip_mismatch	El código postal fiscal no corresponde al RFC en los registros del SAT. Verifica que coincida con la Constancia de Situación Fiscal.
tax_id_not_found	Este RFC del receptor no existe en la lista de RFC inscritos no cancelados del SAT.
tax_system_not_allowed_for_tax_id	El régimen fiscal no está permitido para el RFC en los registros del SAT.
tax_system_not_in_catalog	El régimen fiscal no pertenece al catálogo del SAT.

CustomerErrorCode

Código	Descripción
customer_could_not_be_resolved	No se pudo resolver el cliente.
customer_edit_link_not_found	El enlace de edición del cliente no existe o expiró.
customer_edit_link_unavailable	El enlace de edición del cliente no está disponible.
customer_email_required	Se requiere un correo electrónico del cliente.
customer_has_invoices	No se puede eliminar un cliente con facturas asociadas.
customer_not_found	No se encontró el cliente.
customer_tax_info_unavailable	La información fiscal del cliente no está disponible.

ProductErrorCode

Código	Descripción
product_not_found	No se encontró el producto.

SupplierErrorCode

Código	Descripción
supplier_not_found	No se encontró el proveedor.

CatalogErrorCode

Código	Descripción
product_key_not_found	No se encontró la clave de producto o servicio.
tariff_code_not_found	No se encontró la fracción arancelaria.
unit_key_not_found	No se encontró la clave de unidad.

InvoiceErrorCode

Código	Descripción
invoice_already_stamped	La factura ya fue timbrada.
invoice_not_draft	La factura no es un borrador.
invoice_not_found	No se encontró la factura.
invoice_not_stamped	La factura no ha sido timbrada.

InvoiceDraftErrorCode

Código	Descripción
draft_not_ready_to_stamp	El borrador no está listo para timbrarse.
draft_update_in_progress	El borrador ya se está actualizando.

InvoiceStampingErrorCode

Código	Descripción
invoice_stamping_failed	No se pudo timbrar la factura.
invoice_stamping_service_unavailable	El servicio de timbrado no está disponible.
invoice_stamping_validation_error	La factura no pasó la validación de timbrado.
manifesto_signature_failed	No se pudo firmar el manifiesto.
stamping_in_progress	El timbrado de esta factura ya está en proceso.

InvoiceDeliveryErrorCode

Código	Descripción
invoice_email_delivery_failed	No se pudo enviar la factura por correo.
invoice_email_recipient_required	No tenemos una dirección de correo electrónico registrada para este cliente.
invoice_email_status_not_allowed	No se permite enviar una factura con status {status} por correo.

InvoiceCancellationErrorCode

Código	Descripción
invoice_cancellation_in_progress	La factura tiene una solicitud de cancelación pendiente.
invoice_cancellation_receipt_unavailable	El acuse de cancelación no está disponible.
invoice_cancellation_failed	No se pudo cancelar la factura.
invoice_cancellation_not_allowed	La cancelación de la factura no está permitida.
invoice_cancellation_not_found	No se encontró la solicitud de cancelación.
invoice_cancellation_rfc_mismatch	El RFC no coincide para cancelar la factura.
invoice_cancellation_service_unavailable	El servicio de cancelación no está disponible.
invoice_not_cancelable	La factura no puede cancelarse.
invoice_not_cancelable_by_sat	La factura no puede cancelarse ante el SAT.
substitution_invoice_canceled	La factura de sustitución ya está cancelada.
substitution_invoice_not_found	No se encontró la factura de sustitución.
substitution_invoice_required	Se requiere una factura de sustitución.
substitution_invoice_status_not_allowed	La factura de sustitución no tiene un estatus válido.

ReceiptErrorCode

Código	Descripción
receipt_expired	El recibo expiró.
receipt_not_found	No se encontró el recibo.
receipt_not_open	El recibo no está abierto.

ReceiptInvoicingErrorCode

Código	Descripción
receipt_invoicing_address_mismatch	Todos los recibos deben tener el mismo domicilio de expedición para poder facturarlos juntos.
receipt_invoicing_customer_mismatch	Debes enviar un cliente o seleccionar recibos que ya pertenezcan al mismo cliente.
receipt_invoicing_too_many_items	Los recibos exceden el máximo de 5,000 conceptos soportados. Divide los recibos en varias facturas.
receipt_keys_not_found	No se encontraron los recibos solicitados. Cuando faltan sólo algunas keys, errors[] puede indicar su posición con path: "keys.N".

ReceiptGlobalInvoiceErrorCode

Código	Descripción
global_invoice_too_many_items	La factura global excede el máximo de 5,000 conceptos soportados. Genera varias facturas globales usando rangos de fechas más pequeños o subconjuntos de recibos.
invalid_global_invoice_period	El rango de fechas debe estar dentro del mismo periodo de facturación: {period}.

RetentionErrorCode

Código	Descripción
invalid_retention_complement	El complemento de retención no es válido.
retention_not_found	No se encontró la retención.
retention_not_stamped	La retención no ha sido timbrada.
retention_not_cancelable	La retención no puede cancelarse.

RetentionDeliveryErrorCode

Código	Descripción
retention_email_delivery_failed	No se pudo enviar la retención por correo.
retention_email_recipient_required	No tenemos una dirección de correo electrónico registrada para este cliente.
retention_email_status_not_allowed	No se permite enviar una retención con status {status} por correo.

RetentionCancellationErrorCode

Código	Descripción
retention_cancellation_failed	No se pudo cancelar la retención.
retention_cancellation_service_unavailable	El servicio de cancelación de retenciones no está disponible.

RetentionStampingErrorCode

Código	Descripción
retention_stamping_failed	No se pudo timbrar la retención.
retention_stamping_service_unavailable	El servicio de timbrado de retenciones no está disponible.
retention_stamping_validation_error	La retención no pasó la validación de timbrado.

OrganizationErrorCode

Código	Descripción
invalid_operation	La operación no es válida.
invalid_user_id	El usuario no es válido.
organization_not_found	No se encontró la organización.
subscription_active_required	La organización requiere una suscripción activa.

OrganizationSettingsErrorCode

Código	Descripción
certificate_expired	El certificado ha expirado.
certificate_file_required	No pudimos encontrar un archivo con el nombre "cer" en tu petición. Asegúrate de que tu petición sea de tipo multipart/form-data y de usar "cer" como la llave del atributo.
certificate_files_invalid	El certificado o la llave privada no son válidos, están incompletos o están dañados.
certificate_files_required	No pudimos encontrar ningún archivo en tu petición.
certificate_fiel_rfc_mismatch	El RFC del certificado no coincide con el RFC de la FIEL.
certificate_invalid	El certificado no es válido.
certificate_not_yet_valid	El certificado aún no puede ser utilizado.
certificate_previous_rfc_mismatch	El RFC del certificado no coincide con el certificado anterior.
csd_required	El certificado no es un CSD. Asegúrate de no estar enviando una FIEL.
fiel_invalid	La FIEL no es válida.
fiel_rfc_mismatch	El RFC de la FIEL no coincide con el RFC del certificado CSD.
fiel_required	El certificado no es una FIEL. Asegúrate de no estar enviando un CSD.
organization_domain_change_not_allowed	El dominio de facturación no se puede modificar una vez elegido. Contáctanos para cambiarlo.
organization_domain_unavailable	El dominio de facturación no está disponible.
organization_settings_invalid	La configuración de la organización no es válida.
organization_support_email_required	Se requiere un correo de soporte para elegir un dominio de facturación.
organization_tax_info_invalid	La información fiscal de la organización no es válida.
private_key_certificate_mismatch	La llave privada no coincide con el certificado.
private_key_file_required	No pudimos encontrar un archivo con el nombre "key" en tu petición. Asegúrate de que tu petición sea de tipo multipart/form-data y de usar "key" como la llave del atributo.
private_key_password_incorrect	La contraseña de la llave privada es incorrecta.

OrganizationInviteErrorCode

Código	Descripción
invite_email_delivery_failed	No se pudo enviar la invitación por correo.
invite_email_mismatch	El correo no coincide con la invitación.
invite_expired	La invitación expiró.
invite_not_found	No se encontró la invitación.
invite_role_unavailable	El rol de la invitación no está disponible.
user_already_in_organization	El usuario ya pertenece a la organización.

OrganizationAccessErrorCode

Código	Descripción
organization_admin_access_cannot_be_removed	No se puede remover el acceso de administrador de la organización.
organization_admin_assignment_cannot_be_edited	No se puede editar la asignación de administrador de la organización.
organization_admin_role_cannot_be_deleted	No se puede eliminar el rol de administrador de la organización.
organization_admin_role_cannot_be_edited	No se puede editar el rol de administrador de la organización.
organization_admin_role_required	Se requiere el rol de administrador de la organización.
organization_id_not_allowed	No se permite enviar organizationId para este scope.
organization_id_required	Se requiere organizationId para este scope.
owner_access_cannot_be_reassigned	No se puede reasignar el acceso del propietario.
owner_access_cannot_be_removed	No se puede remover el acceso del propietario.
role_has_assigned_users	No se puede eliminar un rol con usuarios asignados.
role_template_not_found	No se encontró el template del rol.
role_not_found	No se encontró el rol.
user_access_not_found	No se encontró el acceso del usuario.

OrganizationSeriesErrorCode

Código	Descripción
series_already_exists	La serie ya existe.
series_not_found	No se encontró la serie.

WebhookErrorCode

Código	Descripción
webhook_delivery_attempt_not_found	No se encontró el intento de envío del webhook.
webhook_not_found	No se encontró el webhook.
webhook_signature_invalid	La firma del webhook no es válida.

ToolErrorCode

Código	Descripción
tax_id_validation_failed	No se pudo validar el RFC.
tax_id_validation_service_unavailable	El servicio de validación de RFC no está disponible.

Subcódigos de detalle (errors[].code)

Estos valores aparecen dentro de errors[] para explicar detalles específicos del error raíz. No son códigos raíz.

Validación de entrada

Cuando una solicitud tiene varios campos o valores inválidos, errors[] incluye un detalle por cada uno. Estos subcódigos identifican el problema de cada detalle.

Interpreta el subcódigo junto con path, location y la petición original; los subcódigos son deliberadamente generales y no cambian según el tipo del campo o el flujo del endpoint.

Código	Descripción
amount_exceeds_related_document_balance	El monto pagado no puede ser mayor al saldo anterior del documento relacionado.
exchange_rate_too_large	El tipo de cambio debe ser menor o igual a 1 cuando el pago está en MXN y el documento relacionado en USD.
exchange_rate_too_small	El tipo de cambio debe ser mayor o igual a 1 cuando el pago está en USD y el documento relacionado en MXN.
invalid_format	El valor no cumple el formato esperado.
invalid_length	El valor no cumple la longitud permitida.
invalid_type	El valor no tiene el tipo esperado.
not_found	El valor referencia un recurso que no existe.
not_allowed	El valor no está permitido para este campo.
required	Falta un campo requerido.
too_large	El valor excede el límite permitido.
too_small	El valor está por debajo del mínimo permitido.
unknown_field	El campo no está permitido en esta petición.
invalid_value	El valor no es válido.

Códigos externos

Cuando un sistema externo devuelve un código útil, Facturapi lo conserva en errors[].code y agrega errors[].source para indicar cómo interpretarlo. Por ejemplo, en errores de timbrado, source: "sat" indica que errors[].code corresponde a un código de validación del SAT, como CFDI40145.

Los códigos externos no se enumeran aquí porque pertenecen al sistema que los emite. Para códigos de validación de timbrado emitidos por el SAT, consulta la matriz de errores de CFDI 4.0 publicada dentro de la documentación oficial del Anexo 20.