Errors

The API uses conventional HTTP status codes and JSON error bodies.

Error flow

flowchart TD
    A[Incoming request] --> B{Authenticated?}
    B -->|No| C[401 Unauthorized]
    B -->|Yes| D{Valid input?}
    D -->|No| E[422 Validation errors]
    D -->|Yes| F{Resource in org scope?}
    F -->|No| G[404 Not found]
    F -->|Yes| H[200 / 201 / 204 Success]
    D -->|Server fault| I[500 Internal error]

Error shape

Validation errors (422):

{
  "errors": {
    "tax_id": ["The tax id has already been taken."],
    "ciec_password": ["The ciec password field must be 8 characters."]
  }
}

Single-message errors (404):

{
  "message": "Entity not found"
}

Field-scoped not found (404):

{
  "errors": {
    "entity_id": ["Entity not found"]
  }
}

Status codes

Code	Meaning
`200`	Success
`201`	Resource created
`204`	Success, no body (delete)
`401`	Missing or invalid Basic auth
`404`	Resource not found or not in your organization
`422`	Validation failed
`500`	Unexpected server error

Organization scoping

All resources belong to the authenticated organization. Requesting another organization's UUID returns 404, not 403.

Common validation failures

Entity create

Field	Rule
`tax_id`	Required, 12–13 chars, unique per organization
`name`	Required, max 255 chars
`ciec_password`	Required, exactly 8 chars

Extraction create

Field	Rule
`entity_id`	Required UUID, must exist in your organization
`options.period.to`	Must be on or after `options.period.from`
`options.download_type`	`issued` or `received`

Webhook create

Field	Rule
`url`	Required valid URL

Extraction failures

When status is failed, check failed_reason on the extraction resource.

Cause	What to do
Invalid CIEC	Update entity password, wait for `credential_status: valid`
SAT unavailable	Retry the extraction
Credentials not validated	Wait until `credential_status` is `valid`

Invoice edge cases

Situation	API behavior
XML not yet available	Invoice has metadata only; not listed until processed
PDF unavailable	`has_pdf: false`; CFDI endpoint returns `404` for PDF
PPD invoice, complements not yet extracted	`paid_amount: 0`, `due_amount: total`
Payment complement without original invoice	Complement is stored; aggregates update when the original invoice is extracted

Health check

GET /up — returns service health (no authentication required).