Find the next useful step

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:

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

{
  "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 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. After an ambiguous result, follow Colombia timeout recovery 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.

Keep the request’s business reference and any returned resource ID or UUID.
Retrieve the resource or search using the operation’s supported filters.
If an idempotency key is supported, keep that same key for the same operation.
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.

Start here

Fields by country

Shared examples

Mexico · CFDI examples

Build and troubleshoot

Invoicing

Customers and payments

Mexico · SAT

Accounts

Mexico · SAT catalogs

Find the next useful step

Missing or invalid customer fields

A draft rejects an enum

Match the symptom to the action

When a fiscal request fails

When a request times out

​Missing or invalid customer fields

​A draft rejects an enum

​Match the symptom to the action

​When a fiscal request fails

​When a request times out

Missing or invalid customer fields

A draft rejects an enum

Match the symptom to the action

When a fiscal request fails

When a request times out