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.

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.