Plan an integration that can recover from failure.

Choose a supported public contract

Public customer API access, approved routes, and current version namespace must be confirmed during evaluation. Internal routes are not customer integration surfaces unless an approved operation reference explicitly says otherwise.

Each supported route has a stable route ID, method, authentication scheme, tenant source, permission, entitlement, region rule, rate limit, idempotency behavior, request and response schemas, and audit action. Treat that record as part of the integration design.

• Obtain the current approved operation reference and record its stable route ID.
• Use only the contract format and client approach explicitly supplied for the evaluated release; do not infer payloads from internal behavior.
• Confirm the route’s authentication, tenant, region, permission, entitlement, and rate-limit contract.
• Review deprecation and replacement metadata before depending on an older route.

Respect the request control order

Dayrook handlers load the route contract, validate method and content type, authenticate the principal, resolve the tenant, assert region, authorize RBAC or ABAC, check entitlement and billing, validate the schema, apply the rate limit, and check replay or idempotency before the domain service runs.

An integration should supply only the tenant and region context allowed by the contract. Tenant mismatch is denied before resource details are loaded, and a missing or invalid route contract is not a signal to try an internal endpoint.

Handle collections predictably

The default list model uses cursor pagination with a limit and cursor, returning items, next_cursor, and has_more. The default maximum limit is 250 unless a route declares a smaller boundary.

Filtering and sorting are allow-listed per route. Do not send raw SQL, arbitrary JSON paths, or undeclared fields. Sorting uses an explicit field list, with a leading minus for descending order where the route supports it.

Design mutations and webhooks for replay safety

Use the idempotency contract for every supported mutation so a timeout or retry cannot create duplicate money movements, tickets, jobs, restores, or records. Keep the same key only for an exact replay of the same intended operation.

Inbound provider webhooks validate signature, timestamp, and source before resolving a tenant from a stored provider mapping. The event ID is written to a ledger, safe acknowledgments return quickly, and processing continues through replay-safe workers with a dead-letter runbook.

• Generate and persist an idempotency key for one logical mutation.
• Do not reuse the key with different parameters or a different target.
• Verify provider signatures and timestamps before trusting webhook content.
• Resolve tenants through stored mappings, not untrusted payload text alone.
• Make webhook replay and dead-letter recovery part of pre-production testing.

Handle typed errors and retries

The error envelope identifies a code, human-readable message, request ID, route ID, retryable state, and bounded details. Validation, authentication, permission, entitlement, suspension, not-found, conflict, rate-limit, provider, and internal failures are distinct outcomes.

Retry only when the contract says the state is retryable. Respect retry-after guidance for rate limits, preserve request IDs for support and tracing, and keep secrets or sensitive payloads out of logs and error telemetry.

• Map typed error codes to a user-safe action instead of branching on message text.
• Treat MFA-required as a step-up flow, not a generic permission failure.
• Back off on rate-limited and retryable provider outcomes; do not retry permanent validation or authorization denial.
• Record request and route IDs while redacting credentials, tokens, and protected content.
• Test timeout, conflict, replay, partial provider failure, and recovery before production use.

Continue through this topic

Use the product and operator guides that carry this decision into setup, daily work, control, and verification.

• Network management
• Microsoft cloud management
• Infrastructure operations
• Network and cloud operations guide
• Search provider integration evidence
• MSP platform migration planner