Manejo de errores - Factio

Formato de los errores

La API usa tres formatos según el tipo de error. Errores de dominio, con un código estable:

{
  "error_code": "CERTIFICATE_EXPIRED",
  "detail": "The digital certificate has expired."
}

Errores de validación del payload (422), con el formato estándar de FastAPI:

{
  "detail": [
    {
      "type": "string_pattern_mismatch",
      "loc": ["body", "numeric_code"],
      "msg": "String should match pattern '^\\d{8}$'",
      "input": "12AB5678",
      "ctx": { "pattern": "^\\d{8}$" }
    }
  ]
}

Otros errores, con un mensaje en detail:

{
  "detail": "This operation requires user authentication (JWT). API key authentication is not supported."
}

Un comprobante devuelto o no autorizado por el SRI no es un error HTTP: la emisión responde 202 con status DEVUELTA o REJECTED. Consulta Manejar Rechazos.

Códigos HTTP

HTTP	Cuándo ocurre
`200 OK`	Comprobante autorizado por el SRI, o consulta exitosa.
`202 Accepted`	Emisión procesada sin autorización final: devuelto, no autorizado o pendiente. Revisa `status` y `action_taken`.
`400 Bad Request`	Petición inválida, por ejemplo login sin elegir empresa.
`401 Unauthorized`	API Key ausente, inválida o revocada, u operación que no admite API Key.
`403 Forbidden`	Tu rol no tiene permiso para esta operación.
`404 Not Found`	El recurso no existe en tu empresa.
`409 Conflict`	Conflicto de estado, por ejemplo certificado vencido.
`422 Unprocessable Entity`	Payload inválido o regla de negocio no cumplida.
`503 Service Unavailable`	El SRI no está disponible o el secuencial está ocupado. Reintenta con la misma `idempotency_key`.

Códigos de dominio frecuentes

`error_code`	HTTP	Acción recomendada
`CERTIFICATE_EXPIRED`	`409`	Sube un certificado `.p12` vigente desde el panel.
`TOTAL_MISMATCH`	`422`	Revisa que los montos cuadren.
`RETROACTIVE_DATE_NOT_ALLOWED`	`422`	Usa una fecha de emisión permitida.
`INVALID_STATE_TRANSITION`	`422`	La operación no aplica al estado actual del documento.
`DOCUMENT_NOT_FOUND`	`404`	Verifica el `id` del documento.
`SRI_UNAVAILABLE`	`503`	Reintenta más tarde con la misma `idempotency_key`.
`SEQUENCE_LOCK_TIMEOUT`	`503`	Reintenta con la misma `idempotency_key`.

Si escribes a [email protected], incluye el id del documento y la hora aproximada del request.