Español

English

Español

English

Appearance

Errores comunes ​

Guía para identificar y resolver los problemas más frecuentes al integrar con la API.

Autenticación ​

401 – Token de acceso o API key requeridos ​

  • Causa: No se envió el header de autenticación o la cookie de sesión.
  • Solución: Incluye el header Authorization: Bearer <Key ID>:<Secret> o X-API-Key: <Key ID>:<Secret> en todas las peticiones. Ver Autenticación.

401 – API key inválida ​

  • Causa: Key ID incorrecto, Secret incorrecto o llave revocada.
  • Solución: Verifica que copiaste bien el Key ID y el Secret desde Configuración > Integraciones. Si el Secret se perdió, crea una nueva llave.

401 – API key expirada ​

  • Causa: La llave tenía fecha de expiración y ya venció.
  • Solución: Crea una nueva llave en Configuración > Integraciones y actualiza tu aplicación con el nuevo Key ID y Secret.

401 – No se pudo resolver un usuario (API_KEY_NO_USER) ​

  • Causa: La llave existe y el Secret es correcto, pero en la empresa no hay un usuario activo con rol de propietario o administrador al que enlazar la petición (caso excepcional).
  • Solución: Asegurá que la empresa tenga al menos un administrador activo; si persiste, contactá soporte.

401 – Llevás cookie de sesión y esperabas la API key ​

  • Causa: Si el navegador o cliente envía la cookie accessToken válida, el servidor autentica por sesión web y no usa el header de API key en esa petición.
  • Solución: Para pruebas con llave, ventana privada sin sesión abaco, o cliente sin cookies. Ver Autenticación.

Peticiones mutativas y CSRF (403) ​

En POST, PUT, PATCH y DELETE, el API valida Origin o Referer frente a CORS_ORIGINS, salvo que la petición sea sin Origin/Referer y lleve una API key válida (como curl/Postman/servidor), o sea ruta bajo /webhooks.

403 – Origen no permitido (CSRF_ORIGIN) ​

  • Causa: El cliente envía Origin o Referer que no está en la lista permitida del servidor.
  • Solución: Pedí que añadan tu URL exacta a CORS_ORIGINS en el API, o llamá sin cabeceras de navegador desde backend con API key.

403 – Origen no determinado (CSRF_NO_ORIGIN) ​

  • Causa: Petición mutativa sin Origin/Referer y sin API key válida (p. ej. proxy o extensión que las quita).
  • Solución: Enviá la API key en Authorization o X-API-Key, o usá un cliente que no bloquee esas cabeceras.

403 – Validación de API key fallida (CSRF_API_KEY_ERROR) ​

  • Causa: Error al comprobar la llave en la capa CSRF (p. ej. base de datos).
  • Solución: Reintentá; si continúa, revisá conectividad al API y soporte.

Permisos y sesión web (403) ​

403 – Sesión web requerida (WEB_SESSION_REQUIRED) ​

  • Causa: La ruta solo está pensada para la app web (cambio de compañía, asignación de permisos, etc.), no para integraciones con API key.
  • Solución: Esas operaciones deben hacerse iniciando sesión en abaco; no hay equivalente por API key.

403 – Gestión de llaves no permitida con API key (API_KEY_MANAGEMENT_FORBIDDEN) ​

  • Causa: Intentaste administrar llaves de API usando una API key de integración.
  • Solución: Las llaves solo se crean y revocan desde la aplicación web (Configuración > Integraciones en abaco.hn); no forman parte de la API documentada para integradores.

403 – DELETE no permitido con API key (API_KEY_DELETE_FORBIDDEN) ​

  • Causa: Enviaste una petición DELETE usando solo API key.
  • Solución: Eliminá el recurso desde la aplicación web con sesión iniciada, o usá cancelación / reversión cuando el API lo exponga con POST (según el caso).

429 – Demasiadas peticiones (RATE_LIMIT_EXCEEDED) ​

  • Causa: Superaste el límite de peticiones por API key en la ventana de tiempo (cuando aplica; ver Límites y cuotas).
  • Solución: Backoff y menos concurrencia; ver la guía de límites.

Endpoint y red ​

Timeout o conexión rechazada ​

  • Causa: URL base incorrecta, firewall o red inestable.
  • Solución: Confirma que usas el endpoint correcto (producción: https://api.abaco.hn). Revisa que tu entorno permita salida HTTPS al puerto 443.

404 – Not Found en la ruta base ​

  • Causa: Falta el path del recurso o la URL base está mal formada.
  • Solución: La URL base es solo el origen (ej. https://api.abaco.hn). Cada petición debe usar una ruta completa, por ejemplo GET https://api.abaco.hn/business-partners.

Datos y validación ​

400 – Bad Request / errores de validación ​

  • Causa: Body o parámetros inválidos (campos requeridos faltantes, formatos incorrectos).
  • Solución: Revisa el cuerpo de la respuesta; suele incluir detalles por campo. Consulta la Referencia de API para tipos y requisitos.

403 – Forbidden (otros) ​

  • Causa: Permiso de negocio denegado, facturación/SaaS bloqueando acceso, u otro code en el cuerpo de la respuesta.
  • Solución: Leé el message y el code del JSON. Si no es uno de los anteriores, verifica que la llave pertenece a la compañía correcta y que el recurso existe para esa compañía.

Próximos pasos ​

Documentación API abaco · Changelog

© abaco