EasyBankData.

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:

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ó.