Códigos de error de la API
Todo error de la API tiene la misma forma: un code estable que lee un programa, un message que
lee una persona, los details que hagan falta para entenderlo y un request_id para citarlo al
escribirnos. El estado de la respuesta dice si la petición salió bien; aquí nunca se responde
«200» con un error dentro.
⚠️ Los códigos en inglés son a propósito: son identificadores para el programa, como los nombres
de campo del contrato. No cambian nunca —hay quien programa contra ellos—; el message, que sí es
para leer, puede reescribirse cuando se mejore la redacción.
| Código | Estado | Cuándo |
|---|---|---|
authentication_required |
401 | La petición no trae clave, o no viene en la cabecera de autorización como testigo del tipo Bearer. |
invalid_key |
401 | La clave no vale: no existe, se revocó, caducó o su emisor ya no está. Es el mismo código para los cuatro casos, a propósito. |
forbidden |
403 | La clave vale, pero quien la emitió no tiene permiso para esto en ese inquilino: su rol es de solo lectura y la petición modifica, por ejemplo. |
plan_capability_missing |
403 | El plan del inquilino no incluye esta capacidad. details.capability dice cuál falta. |
key_permission_missing |
403 | La clave no tiene permiso para este recurso: se emitió con permisos por recurso y a este le falta el nivel que pide la petición (leer, o leer y escribir). details.resource dice el recurso, details.required_access el nivel que hace falta y details.granted_access el que tiene. Se cambia emitiendo otra clave en el panel. |
not_found |
404 | La dirección o el recurso no existen, o la clave no alcanza ese inquilino. Los dos casos responden lo mismo: distinguirlos confirmaría que el inquilino existe. |
endpoint_retired |
410 | Esa operación se retiró y no vuelve: la conciliación con facturas se hace en el módulo del ERP y el servicio ya no recibe facturas ni documentos. details.docs lleva la dirección que explica el cambio. Un integrador no tiene nada que reintentar: debe dejar de llamarla. |
validation_failed |
400 | Algún parámetro o algún campo del cuerpo no se admite. details dice cuál y por qué. |
method_not_allowed |
405 | Esa dirección no atiende ese método. La cabecera Allow dice cuáles atiende. |
idempotency_conflict |
409 | Se reutilizó una clave de idempotencia con un contenido distinto. La primera petición se atendió; esta no se ha ejecutado. |
rate_limit_exceeded |
429 | Demasiadas peticiones en poco tiempo (límite por clave, contra el abuso). Retry-After dice cuántos segundos esperar. |
plan_quota_exceeded |
429 | Esa conexión ha gastado las lecturas del día que le da su plan (automáticas o manuales, en 24 horas móviles). details.connection_id dice cuál y details.kind qué cubo; Retry-After, cuándo se libera el siguiente hueco. Las demás conexiones no están afectadas y los datos ya descargados siguen disponibles. |
provider_quota_exceeded |
429 | Un tope del proveedor, no del plan: el techo de lecturas de esa conexión en 24 horas (details.scope = connection) o las conexiones distintas del mes de la clave compartida (shared_connections, al conectar un banco nuevo). Se repone solo: no hay nada que hacer salvo esperar (Retry-After). |
plan_connections_exceeded |
403 | El plan del inquilino admite un número de conexiones bancarias y ya las tiene todas. Para conectar otra, retira una o mejora de plan: esperar no conecta nada. |
subscription_unpaid |
403 | La suscripción del inquilino no está al día, así que las lecturas que nadie ha pedido están detenidas. Una persona sí puede pedir una lectura desde el panel. |
connection_needs_reauth |
409 | Esa conexión ya no tiene un acceso vivo: hay que volver a autorizarla llevando a su usuario a la dirección de conexión. details.connect_url la lleva. |
connection_requires_2fa_each_sync |
409 | El banco de esa conexión pide doble factor en cada lectura, así que no se puede leer por la API ni se lee sola (requires_2fa_each_sync de la conexión). Para traer lo nuevo, lleva a su titular a details.connect_url (el widget, en el formulario de su banco) o crea una sesión de conexión con reauthorize_connection. |
session_not_cancellable |
409 | La sesión de conexión ya no se puede cancelar: su titular está autorizando el acceso en el banco, o la sesión ya terminó. details.status dice en qué estado está. |
reauthorization_not_sent |
409 | El enlace de reautorización no se ha mandado al titular: la conexión no tiene titular (no_holder), el titular pidió no recibir avisos (holder_opted_out), se mandó hace menos de 24 horas (too_soon) o ya salió uno hoy (already_today), la conexión no se puede renovar (not_reauthorizable), el plan no deja conectar bancos (plan) o el correo no salió (not_delivered). details.reason dice cuál y details.retry_at, cuándo se podrá. |
account_unbalanced |
409 | La cuenta no cuadra con el saldo del banco (o aún no tiene uno con el que comprobarla): su Norma 43 tendría un saldo final que no es el del banco. Pídelo con accept_unbalanced=true para generarlo igualmente. |
erp_entry_conflict |
409 | El movimiento ya está marcado como llevado a un ERP con otra referencia u otro sistema: dos ERP sobre la misma empresa, o un módulo reinstalado. La marca que había no cambia; details.system y details.reference dicen cuál es. Para cambiarla, quítala antes (DELETE .../erp_entry). |
invalid_grant |
400 | El código de autorización no se puede canjear: no existe, caducó (10 minutos), ya se canjeó, la redirect_uri no es exactamente la de la autorización o el code_verifier no casa con el reto. Un código solo admite un intento: vuelve a autorizar desde el ERP. |
provider_error |
502 | El banco ha fallado al atender una lectura. details lleva el código del proveedor tal cual, sin traducir. |
internal_error |
500 | Algo ha fallado de nuestro lado. Con el request_id localizamos la petición; no hace falta que cambies nada. |
Los «no puedo» que no son lo mismo
Se distinguen porque lo que tiene que hacer quien integra es distinto en cada caso, y confundirlos cuesta dinero o tiempo:
rate_limit_exceeded— vas demasiado rápido. Espera lo que diceRetry-After(segundos) y vuelve a intentarlo: la misma petición vale.plan_quota_exceeded— esa conexión ha gastado las lecturas del día de su plan (en 24 horas móviles). Se repone sola, o se contrata una lectura extra o se cambia de plan. Lo que ya está descargado sigue disponible: leer no gasta.provider_quota_exceeded— el techo es del proveedor, no del plan: el de la conexión en 24 horas, o las conexiones distintas del mes de la clave compartida al conectar un banco nuevo (details.scope). Se repone solo; no hay nada que el cliente pueda hacer salvo esperar.plan_connections_exceeded— no es cupo, es sitio: el plan admite un número de conexiones y ya están todas. Esperar no conecta nada; hay que retirar una o mejorar de plan.subscription_unpaid— no falta plan ni cupo, falta un pago. Lo que se ha detenido son las lecturas que nadie pidió: una persona puede pedir una desde el panel, y sus datos siguen ahí.connection_needs_reauth— esa conexión necesita que su usuario vuelva a autorizarla. No es un error de la petición: es un estado de la conexión, y por eso no se arregla reintentando.connection_requires_2fa_each_sync— no es un estado, es cómo funciona ese banco: pide doble factor en CADA lectura. Nunca se leerá sola; cada lectura la hace su titular en el widget.
Códigos del proveedor
Cuando el fallo viene del banco (provider_error, o una lectura fallida), details.code lleva el
código del proveedor tal cual, sin traducir, porque quien integra puede necesitarlo para su
propio soporte. Los tres que hay que conocer: 2000 es credenciales incorrectas —y reintentarlo
puede bloquear la cuenta del cliente—, 1001 es un error al formatear un dato, y 3 es la
señal de que el consentimiento murió.