Error handling

The API returns errors as JSON and uses standard HTTP status codes. For programmatic error handling, use code: it is a stable, predictable string.

message is meant for humans. Today, API messages are returned in Spanish. They may change to improve clarity or support localization, so avoid using them for branching logic.

Error object

{
  "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"
    }
  ]
}

Field	Type	Description
ok	boolean	Always false for error responses. You can ignore it for programmatic handling.
message	string	Human-readable error message.
status	number	HTTP status code.
code	string	Stable root code for handling the error.
location	string	Location of the data related to the error, such as body, query, params, or files. Included only when applicable.
path	string	Path of the field related to the error. Included only when applicable.
errors	array	Actionable details to correct the request or understand an external response. It can include multiple items when multiple issues are detected.
errors[].message	string	Human-readable message for a detail.
errors[].code	string	Detail subcode. Facturapi validation errors use an input-validation or tax-information-validation subcode; external errors may use the original SAT or PAC code.
errors[].location	string	Location of the data related to the detail, such as body, query, params, or files.
errors[].path	string	Path of the field related to the detail.
errors[].source	string	Source of the detail. It can be facturapi, sat, or pac.

Interpreting codes

The root code classifies the main result of the request and is the value you should check first when deciding how to handle an error.

The errors[] array appears when the response needs to explain one or more details in addition to the main outcome: for example, multiple invalid fields in the same request or reasons returned by an external provider. Its codes are detail subcodes and do not replace the root code. When source is facturapi, the subcode and message are defined by Facturapi. When source is external, the subcode may be the original code from the indicated system.

When an error uses its default root message, message repeats the first detail message in errors[]. This preserves a useful message for integrations that do not yet process structured details; for programmatic logic, always use code, errors[].code, and path.

Validation errors

When the request does not match the input contract, the root error uses code: "invalid_request". When details are available, errors[] includes each invalid field with source: "facturapi", path, location, and a validation subcode.

Validation subcodes are documented at the end of this page as detail subcodes because they appear in errors[].code, not in the root code.

External errors

Some operations depend on external validations or services, such as SAT or PAC. In those cases, the root code remains a Facturapi code, for example invoice_stamping_validation_error.

If the external provider returns useful details that Facturapi cannot classify reliably, they are included in errors[] with the original code:

{
  "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
}

For SAT stamping validation codes, see the CFDI 4.0 error matrix published as part of SAT's official Anexo 20 documentation.

Useful headers

Some error responses include useful headers for programmatic handling or observability:

Header	Description
Retry-After	Recommended seconds to wait before retrying. Included in errors with code: "rate_limit_exceeded".
X-Facturapi-Log-Id	Request correlation ID. You can keep it in your observability stack to investigate errors with support.

Root error codes (code)

This list is the documented reference for public root API codes. We may add new codes at any time when new features or new error cases require them, but we aim to keep this page up to date so integrations have a predictable reference.

CommonErrorCode

Code	Description
conflict	The request cannot be completed because of a conflict.
forbidden	The authenticated caller does not have permission for this action.
internal_error	An unexpected internal error occurred.
not_found	The requested resource was not found.
unauthorized	The request could not be authenticated.

AuthErrorCode

Code	Description
api_key_invalid	The provided API key is invalid.
api_key_not_allowed	The API key cannot perform this action.
feature_not_available	The feature is not available for the organization.
live_api_key_required	The operation requires a live API key.
mcp_permission_denied	The caller does not have permission to use this MCP tool.
missing_credentials	The request did not include credentials.
organization_incomplete	The organization is not fully configured for this operation.
subscription_required	The operation requires an active subscription.
subscription_live_access_required	The subscription does not allow live-mode access.
user_key_invalid	The provided user key is invalid.
user_suspended	The user is suspended.

RequestErrorCode

Code	Description
idempotency_key_in_use	The idempotency key is already being used by another request.
rate_limit_exceeded	The request exceeded the allowed rate limit.
date_range_too_large	The requested date range exceeds the allowed limit.
image_file_required	An image file is required.
invalid_country_code	The country code is invalid.
invalid_date	The date is invalid.
invalid_date_range	The date range is invalid.
invalid_image_file	The provided file is not a valid image.
invalid_json	The request body is not valid JSON.
invalid_request	The request is invalid.
invalid_multipart_form_data	The multipart/form-data payload is invalid.
invalid_state_code	The state code is invalid.
invalid_timezone	The timezone is invalid.
multipart_limit_exceeded	The multipart/form-data request exceeds the allowed limits.
page_too_large	The requested page exceeds the allowed limit.
payload_too_large	The request payload exceeds the maximum allowed size.

TaxInfoValidationCode

These codes describe tax-information errors validated by Facturapi. When a customer or organization tax-information validation detects a single issue, it appears in code. Input validations and the customer tax-information validation endpoint return them in errors[].code.

Code	Description
legal_name_mismatch	The name or business name does not match the RFC in SAT records. Verify that it exactly matches the Tax Status Certificate (Constancia de Situación Fiscal).
tax_address_zip_mismatch	The fiscal zip code does not match the RFC in SAT records. Verify that it matches the Tax Status Certificate (Constancia de Situación Fiscal).
tax_id_not_found	The receiver RFC does not exist in SAT's list of registered, non-cancelled RFCs.
tax_system_not_allowed_for_tax_id	The tax regime is not allowed for the RFC in SAT records.
tax_system_not_in_catalog	The tax regime does not belong to the SAT catalog.

CustomerErrorCode

Code	Description
customer_could_not_be_resolved	The customer could not be resolved from the request or related resources.
customer_edit_link_not_found	The customer edit link does not exist or has expired.
customer_edit_link_unavailable	The customer edit link is not available.
customer_email_required	The customer email address is required.
customer_has_invoices	The customer cannot be deleted because it has associated invoices.
customer_not_found	The customer was not found.
customer_tax_info_unavailable	The customer tax information is not available.

ProductErrorCode

Code	Description
product_not_found	The product was not found.

SupplierErrorCode

Code	Description
supplier_not_found	The supplier was not found.

CatalogErrorCode

Code	Description
product_key_not_found	The SAT product or service key was not found.
tariff_code_not_found	The tariff fraction was not found.
unit_key_not_found	The SAT unit key was not found.

InvoiceErrorCode

Code	Description
invoice_already_stamped	The invoice has already been stamped.
invoice_not_draft	The invoice is not a draft.
invoice_not_found	The invoice was not found.
invoice_not_stamped	The invoice has not been stamped.

InvoiceDraftErrorCode

Code	Description
draft_not_ready_to_stamp	The draft is not ready to be stamped.
draft_update_in_progress	The draft is already being updated.

InvoiceStampingErrorCode

Code	Description
invoice_stamping_failed	The invoice could not be stamped.
invoice_stamping_service_unavailable	The stamping service is unavailable.
invoice_stamping_validation_error	The invoice failed stamping validation.
manifesto_signature_failed	The manifesto could not be signed.
stamping_in_progress	Stamping for this invoice is already in progress.

InvoiceDeliveryErrorCode

Code	Description
invoice_email_delivery_failed	The invoice could not be sent by email.
invoice_email_recipient_required	No email recipient is available for the invoice.
invoice_email_status_not_allowed	The invoice status does not allow email delivery.

InvoiceCancellationErrorCode

Code	Description
invoice_cancellation_in_progress	The invoice already has a pending cancellation request.
invoice_cancellation_receipt_unavailable	The cancellation receipt is not available.
invoice_cancellation_failed	The invoice could not be canceled.
invoice_cancellation_not_allowed	Invoice cancellation is not allowed.
invoice_cancellation_not_found	The cancellation request was not found.
invoice_cancellation_rfc_mismatch	The RFC does not match for invoice cancellation.
invoice_cancellation_service_unavailable	The cancellation service is unavailable.
invoice_not_cancelable	The invoice cannot be canceled.
invoice_not_cancelable_by_sat	The invoice cannot be canceled with SAT.
substitution_invoice_canceled	The substitution invoice is already canceled.
substitution_invoice_not_found	The substitution invoice was not found.
substitution_invoice_required	A substitution invoice is required.
substitution_invoice_status_not_allowed	The substitution invoice status is not valid for this operation.

ReceiptErrorCode

Code	Description
receipt_expired	The receipt has expired.
receipt_not_found	The receipt was not found.
receipt_not_open	The receipt is not open.

ReceiptInvoicingErrorCode

Code	Description
receipt_invoicing_address_mismatch	All receipts must have the same expedition address to be invoiced together.
receipt_invoicing_customer_mismatch	Send a customer or select receipts that already belong to the same customer.
receipt_invoicing_too_many_items	The receipts exceed the maximum of 5,000 supported items. Split the receipts into multiple invoices.
receipt_keys_not_found	The requested receipts were not found. When only some keys are missing, errors[] may point to their position with path: "keys.N".

ReceiptGlobalInvoiceErrorCode

Code	Description
global_invoice_too_many_items	The global invoice exceeds the maximum of 5,000 supported items. Create multiple global invoices using smaller date ranges or receipt subsets.
invalid_global_invoice_period	The date range must be within the same billing period: {period}.

RetentionErrorCode

Code	Description
invalid_retention_complement	The retention complement is invalid.
retention_not_found	The retention was not found.
retention_not_stamped	The retention has not been stamped.
retention_not_cancelable	The retention cannot be canceled.

RetentionDeliveryErrorCode

Code	Description
retention_email_delivery_failed	The retention could not be sent by email.
retention_email_recipient_required	No email recipient is available for the retention.
retention_email_status_not_allowed	The retention status does not allow email delivery.

RetentionCancellationErrorCode

Code	Description
retention_cancellation_failed	The retention could not be canceled.
retention_cancellation_service_unavailable	The retention cancellation service is unavailable.

RetentionStampingErrorCode

Code	Description
retention_stamping_failed	The retention could not be stamped.
retention_stamping_service_unavailable	The retention stamping service is unavailable.
retention_stamping_validation_error	The retention failed stamping validation.

OrganizationErrorCode

Code	Description
invalid_operation	The operation is invalid.
invalid_user_id	The user is invalid.
organization_not_found	The organization was not found.
subscription_active_required	The organization requires an active subscription.

OrganizationSettingsErrorCode

Code	Description
certificate_expired	The certificate has expired.
certificate_file_required	We could not find a file named "cer" in your request. Make sure your request uses multipart/form-data and uses "cer" as the field name.
certificate_files_invalid	The certificate or private key is invalid, incomplete, or damaged.
certificate_files_required	We could not find any files in your request.
certificate_fiel_rfc_mismatch	The certificate RFC does not match the FIEL RFC.
certificate_invalid	The certificate is invalid.
certificate_not_yet_valid	The certificate cannot be used yet.
certificate_previous_rfc_mismatch	The certificate RFC does not match the previous certificate.
csd_required	The certificate is not a CSD. Make sure you are not sending a FIEL.
fiel_invalid	The FIEL is invalid.
fiel_rfc_mismatch	The FIEL RFC does not match the CSD certificate RFC.
fiel_required	The certificate is not a FIEL. Make sure you are not sending a CSD.
organization_domain_change_not_allowed	The invoicing domain cannot be changed after it has been selected. Contact us to change it.
organization_domain_unavailable	The invoicing domain is not available.
organization_settings_invalid	The organization settings are invalid.
organization_support_email_required	A support email is required to select an invoicing domain.
organization_tax_info_invalid	The organization tax information is invalid.
private_key_certificate_mismatch	The private key does not match the certificate.
private_key_file_required	We could not find a file named "key" in your request. Make sure your request uses multipart/form-data and uses "key" as the field name.
private_key_password_incorrect	The private key password is incorrect.

OrganizationInviteErrorCode

Code	Description
invite_email_delivery_failed	The invitation could not be sent by email.
invite_email_mismatch	The email address does not match the invitation.
invite_expired	The invitation has expired.
invite_not_found	The invitation was not found.
invite_role_unavailable	The invitation role is not available.
user_already_in_organization	The user already belongs to the organization.

OrganizationAccessErrorCode

Code	Description
organization_admin_access_cannot_be_removed	Organization admin access cannot be removed.
organization_admin_assignment_cannot_be_edited	The organization admin assignment cannot be edited.
organization_admin_role_cannot_be_deleted	The organization admin role cannot be deleted.
organization_admin_role_cannot_be_edited	The organization admin role cannot be edited.
organization_admin_role_required	The organization admin role is required.
organization_id_not_allowed	organizationId is not allowed for this scope.
organization_id_required	organizationId is required for this scope.
owner_access_cannot_be_reassigned	Owner access cannot be reassigned.
owner_access_cannot_be_removed	Owner access cannot be removed.
role_has_assigned_users	The role cannot be deleted because it has assigned users.
role_template_not_found	The role template was not found.
role_not_found	The role was not found.
user_access_not_found	The user access assignment was not found.

OrganizationSeriesErrorCode

Code	Description
series_already_exists	The series already exists.
series_not_found	The series was not found.

WebhookErrorCode

Code	Description
webhook_delivery_attempt_not_found	The webhook delivery attempt was not found.
webhook_not_found	The webhook was not found.
webhook_signature_invalid	The webhook signature is invalid.

ToolErrorCode

Code	Description
tax_id_validation_failed	The RFC could not be validated.
tax_id_validation_service_unavailable	The RFC validation service is unavailable.

Detail subcodes (errors[].code)

These values appear inside errors[] to explain specific details of the root error. They are not root error codes.

Input validation

When a request has multiple invalid fields or values, errors[] includes one detail for each. These subcodes identify the problem in each detail.

Interpret the subcode together with path, location, and the original request. Subcodes are intentionally generic and do not change based on the field type or endpoint flow.

Code	Description
amount_exceeds_related_document_balance	The paid amount cannot exceed the related document's previous balance.
exchange_rate_too_large	The exchange rate must be less than or equal to 1 when the payment is in MXN and the related document is in USD.
exchange_rate_too_small	The exchange rate must be greater than or equal to 1 when the payment is in USD and the related document is in MXN.
invalid_format	The value does not match the expected format.
invalid_length	The value does not match the allowed length.
invalid_type	The value has the wrong type.
not_found	The value references a resource that does not exist.
not_allowed	The value is not allowed for this field.
required	A required field is missing.
too_large	The value exceeds the allowed limit.
too_small	The value is below the allowed minimum.
unknown_field	The field is not allowed in this request.
invalid_value	The value is invalid.

External codes

When an external system returns a useful code, Facturapi preserves it in errors[].code and adds errors[].source to indicate how to interpret it. For example, in stamping errors, source: "sat" means errors[].code is a SAT validation code, such as CFDI40145.

External codes are not enumerated here because they belong to the system that emits them. For SAT stamping validation codes, see the CFDI 4.0 error matrix.