Catálogo de errores

Todos los errores devueltos por la API siguen el formato Problem JSON. Esta página lista los códigos posibles, con HTTP status correspondiente y campos adicionales que pueden venir en el payload.

Para el formato general y manejo recomendado, ver Manejo de errores.

Errores transversales

code	HTTP	Contexto
validation	400	Request mal formado. Trae invalidParams[] con detalle por campo
invalid-format	400	Valor con formato inválido en un campo puntual
invalid-credentials	401	clientId/clientSecret inválidos en POST /v1/auth/login
unauthorized	401	Falta token o credenciales en el request
invalid-token	401	Token JWT mal formado
token-expired	401	El token expiró. Renovar con POST /v1/auth/login
forbidden	403	El caller no tiene permiso sobre el recurso u operación
insufficient-scope	403	El token no tiene los scopes necesarios
resource-not-accessible	403	El recurso existe pero pertenece a otro customer (cliente o asociado fuera de tu scope)
resource-not-found	404	El recurso no existe o no es accesible
idempotency-key-reuse	409	Mismo Idempotency-Key con cuerpo distinto
idempotent-replay	200/201	Respuesta cacheada devuelta para un Idempotency-Key ya visto (opcional; no es error en sí)
rate-limit-exceeded	429	Rate limit superado. La espera viene en el header Retry-After
internal-error	500	Error interno. Reintentable solo si la operación es idempotente. Incluir requestId en reporte a soporte
external-provider-unavailable	502	El proveedor bancario no responde al provisionar CVU. Reintentar
external-provider-timeout	504	Timeout contra el proveedor bancario al provisionar CVU. Reintentar

Cuentas corrientes y recaudadoras

code	HTTP	Contexto
receivable-account-already-exists	409	Ya existe una cuenta para esa combinación. Response incluye existingResourceId
receivable-account-requires-owner	422	POST sin clientId ni associateId
receivable-account-owner-immutable	422	Intento de reemplazar associateId por uno distinto sobre una cuenta activa con CVU provisionado
owner-type-not-supported	422	El tipo de owner no está habilitado en la config del customer
current-account-not-receivable-enabled	422	Intento de emitir comprobante sobre una cuenta MAIN/SUB

Comprobantes

code	HTTP	Contexto
unmatching-receivable-currency-code	422	currencyCode no coincide con el de la cuenta
unmatching-receivable-client-id	422	clientId no coincide con el de la cuenta
receivable-account-associate-conflict	422	Intento de emitir un comprobante con associateId distinto al que tiene la cuenta
missing-parent-receivable	422	Comprobante negativo sin parentReceivableId
parent-receivable-not-modifiable	422	Padre en estado final, no se puede crear hijo
parent-receivable-different-account	422	Padre pertenece a otra cuenta recaudadora
parent-receivable-invalid-type	422	Padre no es de tipo positivo (INVOICE/DEBT)
child-receivables-exceed-parent-amount	422	Suma de hijos > monto del padre
receivable-has-related-items	422	Intento de anular un comprobante con hijos activos (ej. notas de crédito)
updating-receivable-final-status	422	Modificación sobre comprobante en estado final (SETTLED o DISABLED)
missing-invoice-fields	422	Faltan campos AFIP cuando se setea invoiceData. Trae detalle del campo faltante
duplicated-legal-number	409	El legalNumber enviado ya existe para ese customer. Es único por customer cuando se envía

Movements

code	HTTP	Contexto
unmatching-movement-currency-code	422	currencyCode no coincide con la cuenta

Transferencias

code	HTTP	Contexto
unmatching-transfer-currency-code	422	El currencyCode no coincide con el de la cuenta de origen
equal-origin-destination	422	Origen y destino son la misma cuenta
source-account-not-active	422	La cuenta corriente de origen no está activa
transfer-not-cancelable	422	Se intentó cancelar una transferencia que ya no está en SCHEDULED/PENDING_APPROVAL

Destinatarios

code	HTTP	Contexto
duplicated-contact	409	Ya existe un destinatario con el mismo CBU/CVU o alias

Clientes

code	HTTP	Contexto
incomplete-branch	422	Cliente con sucursal sin todos los campos requeridos

Webhooks

code	HTTP	Contexto
invalid-event-type	400	Event type listado no existe
webhook-status-conflict	422	Operación inválida para el estado del webhook (ej. pause sobre ya pausado)

Campos adicionales por error

Algunos errores incluyen campos extra en el payload Problem JSON:

code	Campos adicionales
receivable-account-already-exists	existingResourceId
validation	invalidParams[] con name y reason
missing-invoice-fields	missingFields[]
rate-limit-exceeded	Sin campos extra en el body — la espera viene en el header Retry-After
external-provider-unavailable / -timeout	providerError.code, providerError.detail
internal-error	requestId