Saltar al contenido

Referencia de API

Errores

Cuando algo falla, la API responde con un código HTTP 4xx o 5xx y un cuerpo JSON con el detalle. Los mensajes están en español y nunca incluyen credenciales ni datos internos.

Formato

Respuesta

404
{
  "error": {
    "type": "not_found",
    "code": "resource_missing",
    "message": "No existe un link con id «link_0000000000000000»."
  }
}
error.typestring
Categoría del error. Úsala para decidir cómo reaccionar.invalid_request_errorauthentication_errornot_foundrate_limit_errorinstitution_errorapi_error
error.codestring
Código estable y legible por máquinas. Úsalo en tu lógica; puede haber códigos nuevos.
error.messagestring
Explicación en español para personas. Puede cambiar: no la compares en tu código.

Códigos HTTP

HTTPSignificado
200Todo bien.
201Se creó el recurso (link token).
202Aceptado: la tarea sigue en segundo plano (refresh).
400La solicitud tiene un parámetro inválido.
401Falta la llave o no es válida.
403La llave no tiene permiso para este endpoint.
404El recurso no existe (o pertenece a otro modo u organización).
409El estado del recurso no permite la operación.
413El cuerpo es demasiado grande.
429Demasiadas solicitudes.
500Error de nuestro lado. Puedes reintentar.
codetypeHTTPCuándo ocurre
invalid_bodyinvalid_request_error400El cuerpo no es un objeto JSON válido.
body_too_largeinvalid_request_error413El cuerpo supera 32 KB.
invalid_parameterinvalid_request_error400Un campo tiene el tipo incorrecto o supera su largo máximo.
invalid_holder_typeinvalid_request_error400holder_type falta o no es individual ni business.
invalid_webhook_urlinvalid_request_error400webhook_url no es una URL HTTPS pública válida.
invalid_limitinvalid_request_error400limit no es un entero entre 1 y 100.
invalid_cursorinvalid_request_error400starting_after no corresponde a un elemento de la lista.
invalid_dateinvalid_request_error400since o until no tienen el formato AAAA-MM-DD.
invalid_date_rangeinvalid_request_error400since es posterior a until.
link_disconnectedinvalid_request_error409Se pidió sincronizar un link revocado.
missing_api_keyauthentication_error401Falta el encabezado Authorization.
invalid_api_keyauthentication_error401La llave no es válida o fue revocada.
secret_key_requiredauthentication_error403El endpoint exige una llave secret y se usó una publishable.
resource_missingnot_found404El recurso no existe en tu organización o en el modo de la llave.
credentials_invalidinstitution_error409El banco rechazó la clave del link; hay que reconectar.
action_requiredinstitution_error409El banco pide una acción a la persona; hay que reconectar.
rate_limitedrate_limit_error429Demasiadas solicitudes. Respeta Retry-After.
internal_errorapi_error500Error inesperado de nuestro lado.

Cómo manejarlos

  • invalid_request_error: corrige la solicitud. Reintentar sin cambios dará el mismo error.
  • authentication_error: revisa la llave y su modo. No reintentes en bucle.
  • institution_error: el link necesita que la persona vuelva a conectar su cuenta con el widget.
  • rate_limit_error: espera los segundos que indica el encabezado Retry-After (ver Límites de uso).
  • api_error y errores de red: reintenta con espera exponencial (por ejemplo 1 s, 2 s, 4 s) y un máximo de intentos. Las lecturas y el refresh son seguros de repetir.

Una ruta que no existe responde 404 sin el formato JSON de error. Revisa que la URL empiece con /v1.