> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gigstack.io/llms.txt
> Use this file to discover all available pages before exploring further.

# CFDI Errors Reference

> Integration guide for CFDI Errors Reference

## 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](/quickstart). This is a read-only
lookup. Enter the exact provider code from your error response:

```bash theme={null}
read -r -p 'CFDI error code: ' CFDI_ERROR_CODE
curl --fail-with-body --get "$GIGSTACK_BASE_URL/invoices/errors" \
  -H "Authorization: Bearer $GIGSTACK_API_KEY" \
  --data-urlencode "code=$CFDI_ERROR_CODE" > cfdi-error.json
```

If the request succeeds, inspect the catalog entry:

```bash theme={null}
jq '.data[] | {code, description, explanation, solution, type}' cfdi-error.json
```

**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](/reference/getInvoicesErrors).

| Parameter | Meaning |
| - | - |
| `code` | Exact stored error code. A match returns a one-element `data` array; absence returns `404`. |
| `q` | Case-insensitive substring search across code, description, explanation, and solution. |
| `type` | Category: `invoice`, `receiver`, `sender`, or `unknown`. |
| `limit` | Positive page size; default `50`, capped at `100`. |
| `page` | Positive page number; default `1`. |

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.

```bash theme={null}
curl --fail-with-body --get "$GIGSTACK_BASE_URL/invoices/errors" \
  -H "Authorization: Bearer $GIGSTACK_API_KEY" \
  --data-urlencode 'q=RFC' \
  --data-urlencode 'type=receiver' \
  --data-urlencode 'limit=10' \
  --data-urlencode 'page=1' > cfdi-errors.json
```

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

| Type | Area to investigate |
| - | - |
| `invoice` | Document fields, totals, taxes, or relationships. |
| `receiver` | Recipient fiscal identity, regime, postal code, or use. |
| `sender` | Issuer configuration, certificate, or fiscal identity. |
| `unknown` | Read the actual description; the catalog has no more specific category. |

## Response Schema

### Success Response

| Field | Type | Meaning |
| - | - | - |
| `success` | boolean | `true` for a successful lookup/search. |
| `data` | array | Catalog entries with the five fields described above. |
| `total` | number | Number of matching entries before pagination. |
| `page`, `limit` | number | Current page and page size. Exact-code lookups use `1` for each. |
| `message` | string | Description of the lookup result. |
| `timestamp` | string | ISO timestamp for this endpoint's successful responses. |

### 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:

```json theme={null}
{
  "success": false,
  "error": {
    "code": "resource_not_found",
    "message": "Error code 'UNKNOWN_CODE' not found"
  },
  "timestamp": 0
}
```

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](/recipes/invoice).

## 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](/troubleshooting).

## Related Documentation

* [Invoice error handling](/guides/invoices#error-handling)
* [Responses and retries](/responses)
* [Mexico fields](/countries/mexico)

## Support

Send the method, path, time, status, exact code, and a redacted error body to
[support@gigstack.io](mailto: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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.