Errors, idempotence, and retries

This page describes integration rules that are usually not visible from the endpoint list alone. The goal is to help client systems distinguish validation errors, authorization problems, temporary failures, and domain conflicts.

What to use it for

An integration that works when all goes smoothly is not finished yet. It is finished once it survives a bad night: a network outage, wrong data at the source, an interrupted run. The rules on this page exist so that nobody cleans up by hand afterwards.

• The nightly sync fails halfway through. A network error cuts off an import of three hundred people from the HR system after the hundred and fiftieth. In the morning you run it again from the start. Because the integration uses stable external identifiers and tells create from update, the first hundred and fifty are not created twice. Without that, you would spend the morning finding and deleting duplicates.
• One bad record does not flood the log. An employee has an invalid e-mail in the HR system and the server answers with a validation error. The integration does not retry: the data will not fix itself. It flags the record for correction in the source system. A retry would only repeat the same error a thousand times.
• You sit out an outage without a night-time phone call. Knowspread returns a temporary error for a few minutes. The integration retries briefly, then with exponential backoff, and once the attempt limit is exhausted it stores the last response and hands the matter to a person. In the morning the log shows what happened and where it stopped.

All three situations rest on one decision: identify the error type first, then choose the reaction. The table below is the guide.

Error types

Situation	Typical integration reaction
Invalid token or credentials	Get a new token or escalate bad configuration.
Invalid payload	Fix the data in the source system and do not resend the same request forever.
Object not found	Verify the identifier and company space.
Domain conflict	Resolve the state in Knowspread or change synchronization order.
Temporary error	Retry with backoff and a limit.

Idempotence

Integrations should be designed so safe retries do not create duplicate users, groups, or memberships. In practice this means:

• use stable external identifiers,
• know the current state before a bulk change,
• verify the result after a batch,
• distinguish create, update, and restore scenarios.

Retry strategy

Retries make sense for network errors and temporary server errors. They do not make sense for validation errors where the data will not fix itself.

Recommended pattern:

1. short retry for a network error,
2. exponential backoff,
3. attempt limit,
4. store the last response for audit,
5. manual intervention after repeated failure.

Still to derive from code

• common error response shape,
• status codes per endpoint,
• behavior for partially valid batch requests,
• rate-limiting rules if any.