09. Troubleshooting, logging and recovery

The difference between a ten minute problem and a day of searching is often a single good log entry.

The interface as a product

Errors need classes: 401 requires session, 403 permission, 4xx mostly data correction, 409 conflict resolution and 5xx/timeout limited technical retry. A checkpoint prevents the entire run from restarting.

This makes the connection robust

1. Assign correlation and external IDs for each run and process.
2. Log start, end, route class, status, duration, attempt, checkpoint and result without secrets.
3. Classify errors as permanent, transient, conflict, or unknown.
4. Repeat only transient errors limited.
5. Move technical errors to a clarification queue with an understandable cause.
6. After correction, continue from a safe checkpoint and provide evidence of completeness.

Prove production readiness

• An event can be tracked across systems.
• Logs are data-efficient and access-protected.
• Alarm differentiates between individual problems and system malfunctions.
• Restart does not create a gap or duplicate.

Mistakes that only become expensive during operation

• Complete requests end up in the log and contain secrets.
• Endless retry hides a permanent mapping error.
• A run goes “green” although dead letter cases remain open.

This is what you take with you

Malfunctions become diagnosable work cases with a safe path back into the data stream.

Further information / source

Related topics

1. For integration specialists – connect APIs and external systems › 02. Login and session cookie
2. For integration specialists – connect APIs and external systems › 05. Filter, paginate and large amounts of data
3. For integration specialists – connecting APIs and external systems › 10. Testing, acceptance and production operations

Frequently asked questions