New article
Recently updated
Troubleshooting API 404 Errors
Who is this article for?
Users interested in developing for Ideagen Quality Management (Essentials).
API access and endpoint permissions are required.
When retrieving workflow definitions via the API, you might encounter an "HTTP 404 Not Found" error, despite correct endpoint, environment, and authentication.
This article explains common causes of 404 errors when querying workflow definitions, includes a related support case, and offers solutions.
1. Issue
Wjem attempting to access a workflow definition using the endpoint, you see a "404 Not Found" error.
Although the API account appear to have permissions, the call returns the error. Other API calls using the same credentials worked normally, indicating that:
- Authentication was valid
- Connectivity was not the issue
This means the problem is specific to accessing workflow definitions.
2. Solution
The solution varies based on the root cause. Follow these troubleshooting steps to resolve it.
2.1. Confirm environment and definition ID
Verify that the workflow definition ID exists in the correct environment.
To do this:
- Ensure the base URL exactly matches the tenant where the workflow definition was created.
- Confirm you are not accidentally calling a sandbox or test tenant.
- List all workflow definitions using:
GET /api/workflows/definitions
If the ID does not appear, the definition is not in that environment.
2.2. Verify API permissions
Many workflow systems return 404 instead of 403 when a user lacks access to a workflow resource.
Ensure the service account includes:
- Permissions to view workflow definitions
- Any workflow administration permissions required
- Any additional role-based permissions enforced by your organization
In several cases, the primary root cause is missing or incomplete permission sets on the API service account.
2.3. Validate API Headers
Workflow APIs typically expect specific headers for versioning, content negotiation, and authentication. Missing or incorrect headers can trigger a 404 at route resolution.
Typical required headers include:
| Header | Example value |
|---|---|
| User-Agent | service-account-name |
| Accept | application/vnd.workflow.v1+json |
| Content-Type | application/json |
| Authorization | Bearer |
| Host | your‑tenant‑domain.com |
Additionally:
- Ensure Bearer Token is selected as the authorisation type if using tools like Postman.
- Copy tokens without formatting changes.
2.4. Regenerate authentication token
Tokens may be:
- Expired
- Revoked
- Copied incorrectly
- Formatted incorrectly by certain tools
Generate a fresh API token and retry the request to rule out credential issues.
2.5. Capture console logs
If the issue persists:
- Enable the API client’s console logs
- Collect request and response headers
- Verify URL encoding, method type, and header normalization
These logs help identify hidden header issues or mismatched content types.