Errores

Todos los errores usan el mismo envelope JSON:

{
  "error": {
    "code": "validation_error",
    "message": "Invalid request body"
  }
}

El code es estable y pensado para programar contra él; el message es legible y puede cambiar. El status HTTP acompaña al code.

Catálogo de códigos

`code`	HTTP	Cuándo
`validation_error`	400	El cuerpo o los query params no pasan validación (zod)
`auth_context_error`	400	Falta el contexto de organización (path de sesión)
`unauthorized`	401	API key inválida, revocada o expirada
`forbidden`	403	Se usó una API key en un endpoint solo-sesión (p. ej. crear conexión)
`connection_not_found`	404	La conexión no existe en tu organización
`sync_run_not_found`	404	La corrida de sync no existe en esa conexión
`rcv_document_not_found`	404	El documento RCV no existe
`dispatch_guide_not_found`	404	La guía de despacho no existe
`security_transfer_not_found`	404	La transferencia de Banco Security no existe
`security_nomina_not_found`	404	La nómina de Banco Security no existe
`api_key_not_found`	404	La API key no existe
`external_source_not_found`	404	La fuente externa referenciada no existe
`connection_sync_in_progress`	409	Se intentó eliminar o actualizar credenciales de una conexión con un sync en vuelo
`sync.too_many_pending`	429	Cap de cola excedido: hay demasiadas corridas pendientes para esta conexión
`scope_not_supported`	422	El scope pedido no existe en el conector de la fuente
`scope_not_enabled`	422	El scope pedido existe pero no está habilitado en la conexión
`invalid_sync_metadata`	422	Los metadatos de sync no pasan la validación del scope
`schedule_invalid_frequency`	422	`frequency_minutes` fuera de `{60, 360, 720, 1440}` al activar el schedule
`invalid_credentials`	422	Las credenciales no pasan la validación del conector o falló la prueba de login
`internal_error`	500	Error no controlado del servidor

Notas

Validación: las requests con cuerpo/params inválidos responden 400 validation_error. Los esquemas se validan con zod.
Conexión inexistente: todos los endpoints por conexión (GET /connections/{id}, POST .../sync, GET .../sync-runs, PUT .../schedule, GET .../sii-rcv-documents, etc.) la reportan como 404 connection_not_found.
Secretos: los error_message de las corridas de sync van redactados (RUTs, contraseñas, tokens, cookies → [REDACTED]).
Avisos vs errores: condiciones esperadas e informativas (p. ej. el detalle de guías fuera de la ventana de 6 meses de SII) se exponen como notices en scope_outcomes[], no como errores: no degradan la corrida. Ver Sync → Avisos.

Errores

Catálogo de códigos

Notas

On this page