English

Español

English

Español

Appearance

Common errors ​

Guide to identifying and fixing the most frequent issues when integrating with the API.

Authentication ​

401 – Token or API key required ​

  • Cause: No authentication header or session cookie was sent.
  • Fix: Include the Authorization: Bearer <Key ID>:<Secret> or X-API-Key: <Key ID>:<Secret> header on every request. See Authentication.

401 – Invalid API key ​

  • Cause: Wrong Key ID, wrong Secret, or the key was revoked.
  • Fix: Double-check the Key ID and Secret from Settings > Integrations. If the Secret was lost, create a new key.

401 – API key expired ​

  • Cause: The key had an expiration date and it has passed.
  • Fix: Create a new key under Settings > Integrations and update your app with the new Key ID and Secret.

401 – Could not resolve user (API_KEY_NO_USER) ​

  • Cause: The key exists and the Secret is correct, but no active user with business proprietor or administrator role could be bound for that company (rare).
  • Fix: Ensure the company has at least one active administrator; if it persists, contact support.

401 – Session cookie present but you expected API key ​

  • Cause: If the client sends a valid accessToken cookie, the server authenticates the web session and does not use the API key header on that request.
  • Fix: For key testing, use a private window with no abaco session, or a client without cookies. See Authentication.

Mutating requests and CSRF (403) ​

On POST, PUT, PATCH, and DELETE, the API checks Origin or Referer against CORS_ORIGINS, unless the request has no Origin/Referer and carries a valid API key (as with curl/Postman/server-side), or the path is under /webhooks.

403 – Origin not allowed (CSRF_ORIGIN) ​

  • Cause: The client sends an Origin or Referer not in the server allow list.
  • Fix: Ask the team to add your exact URL to CORS_ORIGINS on the API, or call from the backend without browser headers using an API key.

403 – Origin could not be determined (CSRF_NO_ORIGIN) ​

  • Cause: Mutating request without Origin/Referer and no valid API key (e.g. proxy or extension stripping them).
  • Fix: Send the API key in Authorization or X-API-Key, or use a client that does not strip those headers.

403 – API key validation failed (CSRF_API_KEY_ERROR) ​

  • Cause: Error while validating the key in the CSRF layer (e.g. database).
  • Fix: Retry; if it continues, check API connectivity and support.

Permissions and web session (403) ​

403 – Web session required (WEB_SESSION_REQUIRED) ​

  • Cause: The route is web-app only (change company, user permissions, etc.), not for API key integrations.
  • Fix: Perform those actions while signed into abaco; there is no API key equivalent.

403 – Key management not allowed with API key (API_KEY_MANAGEMENT_FORBIDDEN) ​

  • Cause: You tried to manage API keys using an integration API key.
  • Fix: Keys are only created and revoked in the web app (Settings > Integrations on abaco.hn); that is not part of the documented integration API.

403 – DELETE not allowed with API key (API_KEY_DELETE_FORBIDDEN) ​

  • Cause: You sent a DELETE request using only an API key.
  • Fix: Remove the resource from the web app while signed in, or use cancel/reversal flows exposed as POST where applicable.

429 – Too many requests (RATE_LIMIT_EXCEEDED) ​

  • Cause: You exceeded the per–API key request limit in the time window (when enabled; see Rate limits).
  • Fix: Use backoff and lower concurrency; see the rate limits guide.

Endpoint and network ​

Timeout or connection refused ​

  • Cause: Wrong base URL, firewall, or unstable network.
  • Fix: Confirm you are using the correct endpoint (production: https://api.abaco.hn). Ensure your environment allows outbound HTTPS on port 443.

404 – Not Found on base path ​

  • Cause: Missing resource path or malformed base URL.
  • Fix: The base URL is only the origin (e.g. https://api.abaco.hn). Each request must use a full path, e.g. GET https://api.abaco.hn/business-partners.

Data and validation ​

400 – Bad Request / validation errors ​

  • Cause: Invalid body or parameters (missing required fields, wrong formats).
  • Fix: Check the response body; it usually includes per-field details. See the API reference for types and requirements.

403 – Forbidden (other) ​

  • Cause: Business permission denied, billing/SaaS blocking access, or another code in the response body.
  • Fix: Read the JSON message and code. If it is not one of the cases above, ensure the key belongs to the correct company and that the resource exists for that company.

Next steps ​