Troubleshooting
Troubleshooting
Overview
This guide covers common issues that can occur when integrating with ToastMachine.
The exact response codes and error formats depend on the operation being used. Consult the API specification for the authoritative list of possible responses.
Requests Are Failing
When a request fails:
- Check that the request URL and HTTP method are correct.
- Confirm that the required parameters and headers are present.
- Validate the request body against the documented schema.
- Inspect the HTTP status code and response body.
- Check whether the operation requires authentication.
- Retry only when appropriate for the type of failure.
Do not assume that every failed request can safely be retried.
Authentication Problems
If an authenticated request fails, check that:
- The correct authentication mechanism is being used.
- Required credentials are present and valid.
- Credentials have not been accidentally truncated or altered.
- The request uses the expected headers or other documented authentication fields.
- The requested operation is available to the authenticated identity.
Do not paste private credentials into public issue reports, logs, or documentation.
A Message Cannot Be Found
If a message or conversation cannot be retrieved, check:
- Whether the identifier is correct.
- Whether the resource belongs to the expected corpus or instance.
- Whether the resource is accessible through the requested interface.
- Whether the request uses the correct path and identifier format.
A missing resource response does not necessarily establish why the resource could not be found.
A Write Operation Fails
If you cannot create or append a message:
- Confirm that the operation requires and receives the correct authentication.
- Check required fields and size limits in the API specification.
- Verify that referenced conversations or messages satisfy the documented constraints.
- Inspect the returned error details.
- Determine whether the request may have succeeded before retrying.
If the outcome is uncertain, use the documented retrieval mechanisms to establish the current state before attempting a duplicate write.
Search Does Not Return Expected Results
If a search does not return the content you expected:
- Check the query and any supplied filters.
- Confirm that you are searching the intended resource or corpus.
- Consider retrieving the relevant conversation or message directly if you know its identifier.
- Check whether tags or other discovery mechanisms provide an alternative route to the content.
Do not assume that a search result set represents every potentially relevant contribution unless the API explicitly guarantees that completeness.
Synchronisation Is Interrupted
If a change feed or live stream stops unexpectedly:
- Check the connection and response status.
- Follow the documented reconnection and continuation procedure.
- Resume from the appropriate supported cursor or sequence position, where available.
- Account for possible duplicate observations when rebuilding local state.
- Reconcile your local view using the documented retrieval mechanisms when necessary.
Do not assume that reconnecting to a live stream automatically recovers events missed during disconnection.
Reporting an Issue
When reporting a problem, include information that helps reproduce it:
- The operation and HTTP method.
- The endpoint path, with secrets removed.
- The HTTP status code and relevant error response.
- A redacted example of the request.
- The expected behaviour and the observed behaviour.
- Whether the issue is repeatable.
Never include private credentials, authentication tokens, or sensitive message content in an issue report.
