Skip to main content

​
Overview

When Mexican invoice issuance fails, look up the code actually returned by the provider. The catalog can explain a known fiscal validation error; it does not establish whether an earlier timed-out write completed.

​
How to Use It

Use the environment variables from Quickstart. This is a read-only lookup. Enter the exact provider code from your error response:
If the request succeeds, inspect the catalog entry:
Expected for a known exact code: HTTP 200, data containing one entry, and total: 1, page: 1, limit: 1. An unknown code returns 404; keep the original provider message and use text search or support rather than guessing a replacement.

​
What We See

Entries contain code, description, explanation, solution, and type. Descriptions can be in Spanish. The catalog contains stored explanations and is not a guarantee that every provider or infrastructure error has a matching entry.

​
API Endpoint

​
List CFDI Errors

GET /invoices/errors. See the operation reference. When code is supplied, the handler performs an exact lookup and returns immediately; q, type, page, and limit do not refine that result. Omit code for search. Send positive integers for page and limit; do not rely on validation of negative values.
For a successful search, an empty data array with total: 0 is a valid no-match result. Pagination is page-based, not cursor-based. Continue while page * limit is less than total, preserving the same filters.

​
Error Types

​
Response Schema

​
Success Response

​
Error Responses

The handler’s errors use the standardized error object. An illustrative unknown-code response has this shape; the timestamp and message depend on the request:
The error timestamp is epoch milliseconds, unlike the success timestamp above. HTTP 500 uses error.code: "internal_server_error". Authentication can fail before this handler with a different envelope; always inspect the HTTP status and body.

​
Common Use Cases

​
1. Implementing Error Messages

Display the original provider message together with any matching catalog explanation. Check HTTP status before reading data[0]; 404 is a lookup miss, not a missing invoice.

​
2. Building Error Documentation

Use q or type with page-based pagination. Keep the original code visible so a translated explanation does not obscure the evidence needed for support.

​
3. Validating Before Invoice Creation

Use the request schema for input validation. A successful catalog lookup is not a preflight fiscal validation or a guarantee that the corrected invoice will stamp.

​
Best Practices

Correct the identified field using the underlying transaction or recipient information. Do not silently substitute fiscal codes, reduce totals, or create a second invoice merely because an error explanation suggests a general cause.

​
Integration Example

A useful recovery sequence is: preserve method/path and provider code → look up the code → inspect the affected data → prepare a correction → reconcile any ambiguous prior write → submit only the intended corrected operation. For runnable issuance examples, use the invoice recipe.

​
Important Notes

A catalog read has no fiscal side effect. The invoice or cancellation that prompted it may already have side effects. For a timeout or STAMP_NEEDS_REVIEW, investigate the original write before retrying; see Troubleshooting.

​
Support

Send the method, path, time, status, exact code, and a redacted error body to support@gigstack.io. Include a process-log ID when the provider response supplies one. Keep keys, certificates, customer data, and signed URLs out of the message.