Troubleshooting invalid payloads and ingest failures

1. The payload is valid JSON but ingest still fails

Start by confirming the request includes a valid X-Api-Key header and that the Telemetry.Company value matches the organization configured in Toro Pulse Settings.

Valid JSON is not the same as a valid Toro Pulse ingest payload. The most common failure is that the payload does not include the expected Telemetry envelope or required telemetry fields.

Common failure example:
{
  "processName": "Invoice Intake"
}

Preferred structure:
{
  "Telemetry": {
    "Process": "Invoice Intake"
  }
}

2. Error: "The Telemetry field is required"

This indicates the server-side ingest contract expects a top-level Telemetry object. Use one of the template files and compare property names exactly.

3. Error: invalid JSON

Check for trailing commas.
Use double quotes for keys and string values.
Validate the file in a JSON validator before upload.
Make sure the file extension is .json and the contents are plain text JSON.

4. Drag-and-drop file imports do not load all files

The UI may accept multiple files but still reject individual entries if parsing fails. Review each file independently and start with the minimal template to isolate the first bad file.

5. API returns 500

A 500 response usually points to an application, database, or schema mismatch rather than a user-entry typo. Review application logs for missing columns, type mismatches, or process/session lookup issues.

6. Datasheet values render incorrectly

Confirm numeric fields are sent as numbers, not formatted strings.
Confirm UTC timestamps are ISO 8601 values.
Check that the payload maps to the expected process and tenant context.
Retest with the minimal template before reintroducing optional fields.

Escalation checklist

Save the exact request body that failed.
Capture the HTTP status code and response body.
Record the time of failure and tenant/process context.
Compare against the bundled template files.
Check application logs for server exceptions.