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

# Find the next useful step

> Read an error, fix the right field, and avoid retrying a completed write.

Start with the **HTTP status and response body**. Responses have several shapes;
`success: false` is not present on every error.

## Missing or invalid customer fields

A request such as `{"email":"not-an-email"}` returned HTTP `400`:

```json theme={null}
{
  "success": false,
  "error": {
    "code": "validation_failed",
    "message": "Request validation failed",
    "details": ["name: Missing required field", "email: email"]
  }
}
```

Supply `name` and a valid email address, or omit the optional email. Retrying the unchanged
body will not fix validation. Examples show selected fields; responses can include a timestamp.

## A draft rejects an enum

`invoice_type: "WRONG"` returned `400` with a different shape:

```json theme={null}
{
  "message": "Invalid body",
  "errors": [{
    "path": "invoice_type",
    "code": "invalid_value",
    "expected": "enum(\"I\", \"E\")",
    "received": "\"WRONG\"",
    "message": "Value not in enum"
  }]
}
```

Use `I` for an income draft or `E` for an egress draft. Read the field's enum in the
reference instead of guessing a translated value.

## Match the symptom to the action

| Symptom | What to check next |
| - | - |
| `401`, `Jwt is missing` | Send `Authorization: Bearer ...`. The gateway can reject a call before a handler sees it. |
| `403`, `API Key inválida` | Match the key to its environment; confirm it is still valid. |
| Customer creation succeeds but fiscal validation is `skipped` | Supply the fiscal fields before stamping. Creation alone does not establish SAT validity. |
| `400 resource_conflict` when registering a payment or receipt | Reconcile the existing record referenced by the error. Keep the original key for the same business event. |
| Draft preview says a client and item are missing | Fetch the draft. A partial update may have cleared `items`; resend the complete intended body. |
| Former draft ID returns `404` after stamping | Use `data.uuid` from the stamping response to retrieve the issued invoice. |
| Invoice has `status: valid`, but the customer has not paid | Fiscal validity and payment settlement are separate. Check payment records. |
| Payment creation succeeds, but no complement appears yet | Check the payment's linked invoices and the parent PPD invoice. Automation is asynchronous. |
| A documented operation has an availability warning | Its handler exists, but the public gateway does not route it yet. Do not retry that URL indefinitely. |

## When a fiscal request fails

For **Mexico**, read the returned provider error. Compare the recipient's RFC, legal name, postal code,
regime, and Uso CFDI with the submitted values. Check payment timing, tax amounts,
and the emitting team's certificate setup. Use the [CFDI error catalog](/guides/catalogs/cfdi_errors)
for the code you actually received.

For **Colombia**, compare the exact DIAN/provider message with the customer identity,
municipality, fiscal responsibilities, and [issuer activation and numbering setup](/concepts/issuer-setup#colombia).
After an ambiguous result, follow [Colombia timeout recovery](/countries/colombia#recover-after-a-timeout)
before attempting issuance again.

Change one identified problem at a time. Do not switch a fiscal code simply to bypass
an error if it no longer represents the sale.

## When a request times out

A timeout means you did not receive a result; the operation may still have completed.

1. Keep the request's business reference and any returned resource ID or UUID.
2. Retrieve the resource or search using the operation's supported filters.
3. If an idempotency key is supported, keep that same key for the same operation.
4. For stamping, cancellation, refunds, or ambiguous payment results, reconcile the
   existing state before sending another write.

Retry reads with bounded backoff. Do not apply that policy blindly to writes.
For help, share the method, path, status, time, and a redacted error body—never the key,
certificate, or signed download URL.


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