Common API Errors and Troubleshooting

This article describes common issues developers may encounter when building custom applications for Flowlu and explains how to diagnose and resolve them. Most problems are related to authentication, permission scopes, or user access rights.

Understanding how Flowlu validates API requests will help you avoid errors and build more reliable applications.

Authentication errors (401 / unauthorized)

Symptom

API requests fail with an authentication error or are rejected as unauthorized.

Common causes

• Missing access token in the request

• Expired OAuth 2.0 access token

• Invalid or revoked API key

• Using an API key for an endpoint that requires user identity

How to fix

• Ensure every API request includes valid authentication credentials.

• For user-specific actions, use OAuth 2.0 and pass the access token in the request headers.

• Refresh expired tokens when required.

• Use API keys only for system-level access where user identity is not needed.

See Authentication and Authorization for details.

Permission denied (403 / forbidden)

Symptom

The API request is authenticated but rejected due to insufficient permissions.

Common causes

• Required permission scope is not declared in the application manifest.

• The application was installed without approving all requested scopes.

• The user whose token is used does not have access to the target module.

How to fix

• Verify that the application manifest includes a scope that allows access to the target module and model.

• Reinstall the application if scopes were changed after installation.

• Ensure the user has the necessary access rights in the Flowlu portal.

See Permission Scopes and Data Access for details.

Frontend token misuse

Symptom

API requests work in development but expose sensitive tokens or behave unexpectedly in production.

Common causes

• Using access tokens of other users in frontend code

• Sending privileged tokens from the browser

• Bypassing the Flowlu JS SDK for frontend API calls

How to fix

• Frontend API requests must always use the access token of the currently authenticated user.

• Use the Flowlu JS SDK for frontend API access whenever possible.

• Move sensitive or cross-user operations to backend services.

See Authentication and Authorization for security guidelines.

Webhook creation failures

Symptom

A webhook cannot be created or does not receive events.

Common causes

• The application does not declare a scope for the target module or model.

• The webhook endpoint URL is invalid or unreachable.

• The application version was updated and webhook definitions changed.

How to fix

• Ensure the application manifest declares scopes that allow access to the webhook’s target entities.

• Verify the webhook endpoint is publicly accessible over HTTPS.

• Check whether the current application version defines the webhook correctly.

See Webhooks for Custom Applications for details.

“No access” entity selectors in the UI

Symptom

Entity selectors show empty lists or display only entity IDs with a “no access” indicator.

Common causes

• The application declares a scope for the entity, but the current user does not have permission to access the module.

• The application does not declare a scope for the selected entity type.

How to fix

• Confirm that both conditions are met:

  • the application declares the required scope,

  • the user has access to the corresponding module.

• Test with a user role that has appropriate permissions.

See Permission Scopes and Data Access for details.

Application updates cause missing UI elements

Symptom

After updating an application, certain tabs, widgets, or menu items disappear.

Common causes

• Integration points were removed or changed in the updated manifest.

• The application version no longer declares the integration point.

How to fix

• Compare the previous and current manifests to verify integration points.

• Re-add missing integration points to the manifest if they are still required.

• Reinstall or update the application after correcting the manifest.

See Application Versioning and Updates for update behavior.

General debugging recommendations

• Log API responses and error messages during development.

• Test with different user roles to verify permission behavior.

• Avoid hardcoding tokens or assumptions about access rights.

• Treat permission errors as configuration issues, not platform bugs.