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
| HTTP | Significado |
|---|---|
| 200 | Todo bien. |
| 201 | Se creó el recurso (link token). |
| 202 | Aceptado: la tarea sigue en segundo plano (refresh). |
| 400 | La solicitud tiene un parámetro inválido. |
| 401 | Falta la llave o no es válida. |
| 403 | La llave no tiene permiso para este endpoint. |
| 404 | El recurso no existe (o pertenece a otro modo u organización). |
| 409 | El estado del recurso no permite la operación. |
| 413 | El cuerpo es demasiado grande. |
| 429 | Demasiadas solicitudes. |
| 500 | Error de nuestro lado. Puedes reintentar. |
Catálogo de códigos
| code | type | HTTP | Cuándo ocurre |
|---|---|---|---|
invalid_body | invalid_request_error | 400 | El cuerpo no es un objeto JSON válido. |
body_too_large | invalid_request_error | 413 | El cuerpo supera 32 KB. |
invalid_parameter | invalid_request_error | 400 | Un campo tiene el tipo incorrecto o supera su largo máximo. |
invalid_holder_type | invalid_request_error | 400 | holder_type falta o no es individual ni business. |
invalid_webhook_url | invalid_request_error | 400 | webhook_url no es una URL HTTPS pública válida. |
invalid_limit | invalid_request_error | 400 | limit no es un entero entre 1 y 100. |
invalid_cursor | invalid_request_error | 400 | starting_after no corresponde a un elemento de la lista. |
invalid_date | invalid_request_error | 400 | since o until no tienen el formato AAAA-MM-DD. |
invalid_date_range | invalid_request_error | 400 | since es posterior a until. |
link_disconnected | invalid_request_error | 409 | Se pidió sincronizar un link revocado. |
missing_api_key | authentication_error | 401 | Falta el encabezado Authorization. |
invalid_api_key | authentication_error | 401 | La llave no es válida o fue revocada. |
secret_key_required | authentication_error | 403 | El endpoint exige una llave secret y se usó una publishable. |
resource_missing | not_found | 404 | El recurso no existe en tu organización o en el modo de la llave. |
credentials_invalid | institution_error | 409 | El banco rechazó la clave del link; hay que reconectar. |
action_required | institution_error | 409 | El banco pide una acción a la persona; hay que reconectar. |
rate_limited | rate_limit_error | 429 | Demasiadas solicitudes. Respeta Retry-After. |
internal_error | api_error | 500 | Error 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 encabezadoRetry-After(ver Límites de uso).api_errory 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.