API Troubleshooting¶

For details on paylaods and formatting API commands, please see the API Documentation.

Problem	Solution
Authentication errors when calling the API.	- All Falkonry APIs require token-based authentication. Make sure you have a valid API token generated from the TSI UI. - Add the token to your requests using the header: `Authorization: Bearer <your-access-token>`

Problem	Solution
Token stopped working or expired.	- Tokens expire (e.g., 30 days for some CMMS/EAM connections via Makini). - Generate a new token in the TSI UI and delete the old one.

Problem	Solution
Limited or missing API access.	- Access depends on your role: Owner = full access, including managing users and tokens Manager/User = limited access

Problem	Solution
API results are incomplete or truncated.	- Most APIs limit records returned (typically 50, up to 1000 for alerts). Use pagination with `offset/limit` or `next-time` headers to get more results.

Problem	Solution
Uncertainty about which model ID to use.	- For information on the model you built, use the M[#] for your source model. - For active live model output that includes changes, use M[0] or the live model.

Problem	Solution
Time-based queries failing.	- Use ISO 8601 for query parameters unless otherwise specified in API call instructions, e.g.: `start_time_iso=2023-01-01T00:00:00.000000Z` `end_time_iso=2023-01-02T00:00:00.000000Z`

Problem	Solution
Confusion about HTTP response codes.	- `2xx` = success - `4xx` = client error (bad request, authentication issue, invalid input) - `5xx` = server error

Problem	Solution
Unsure if operations completed successfully.	- Many tasks (signal approval, historical evaluations, model output generation) are tracked as flows. Check their status (CREATED, RUNNING, COMPLETED, FAILED) in the Activity view UI. - You can also use the API to get more details by doing a GET request at the `/flows/{flow_id}` endpoint

Problem	Solution
Outbound connection stuck on “PAUSED”.	- TSI failed to connect to the external system after several retries. - Review the error details in the Connection UI, resolve the issue (e.g., whitelist Falkonry IPs), and then set the status back to PRODUCTION.

Problem	Solution
401 Unauthorized — authentication failed.	- Check that your API token is valid and hasn’t expired. - Ensure you are sending the token in the request header: `Authorization: Bearer <your-access-token>` - Verify your user role has access to the requested endpoint.

Problem	Solution
403 Forbidden — access denied.	- Your account or role doesn’t have permission for this API. - Confirm that your role (Owner, Manager, User) allows access. - Contact your administrator to request necessary permissions.

Problem	Solution
400 Bad Request — invalid request format.	- Check the API request parameters for typos, missing fields, or invalid values. - Confirm your JSON payload or query parameters match the API documentation. - Ensure timestamps and number formats follow the expected standards (ISO 8601, US decimal format).

Problem	Solution
500 Internal Server Error — server-side issue.	- Retry the request after a few seconds; it may be a transient issue. - Check the Falkonry status page for ongoing outages. - If persistent, contact support with your request details.

Problem	Solution
404 Not Found — endpoint or resource doesn’t exist.	- Verify the endpoint URL is correct and active. - Check that you’re using the correct model ID or resource identifier. - Ensure the API version matches the documentation and hasn’t been deprecated.

Problem	Solution
Request timed out.	- Check your network connection and firewall settings. - Reduce the amount of data requested in a single API call. - Use pagination or filtering to limit the response size. - Retry after a short delay to see if the issue persists.