Troubleshoot ingest

Use this guide when a sender receives an error or cannot determine whether a request succeeded. For status definitions, see the HTTP reference.

Handle HTTP errors

Inspect the HTTP status and response body, including any field-level validation messages. Then use the appropriate recovery action:

Symptom	Action
400: invalid request or payload	Correct the fields named in the response. Check required headers, JSON structure, asset ID, and the registered data type/version. For ISO 19848, check the DataChannelList reference and channel/value alignment.
400 or 413: payload too large	Measure the serialized body against the request limits. Split JSON into smaller batches, or upload a file as an attachment.
401: authentication or ownership rejected	Check the target environment, ApiKey authorization scheme, and ingest credential. For attachments, use the connection that sent the parent package. Follow authentication setup if a key needs replacing.
404: route or parent package not found	Check the URL and resource ID. An attachment needs the Gateway's returned packageId, not your external ID. Confirm the parent request succeeded in the same environment.
429: rate exceeded	Delay further sends and reduce the rate. Coordinate all traffic sharing the ingest connection; avoid releasing a buffered backlog as a burst.
500: unexpected server error	Contact your DNV representative with the request details described below, excluding the API key. Retain the payload while the failure is investigated.
Other 5xx: service or dependency failure	Retain the payload and retry with bounded backoff. Escalate repeated failures to your DNV representative.

Do not repeatedly retry unchanged requests with validation or authentication errors. Correct the request or credentials first.

Recover from timeouts and interruptions

1. Keep unsent data in durable storage in your sending system, with its original measurement timestamps.
2. Record a request without a response as an uncertain outcome, not a confirmed rejection. The Gateway may already have accepted it.
3. Retry transient failures with bounded exponential backoff and jitter. Limit attempts and surface exhausted retries to your operators.
4. Account for possible duplicates when resending. External and correlation IDs provide traceability, not deduplication.

For why retries can duplicate data, see delivery and batching.

Collect details for support

Record the send time, environment, route, asset ID, external/correlation IDs, HTTP status, response error details, and returned package ID if available. Include these details when reporting a failure to your DNV representative. Keep API keys and unrelated customer data out of logs and support requests.

Check recovery before production

In customer test, exercise validation errors, rate limits, and a network interruption. Confirm the sender retains failed batches and resumes without silently dropping data. For ISO 19848, also confirm the DataChannelList version and ShortID mappings. Coordinate production credentials and activation with DNV.