Should every 5xx response be retried?
Not automatically. Consider whether the operation is safe to repeat, whether the provider marks the error transient and whether an ambiguous side effect must be reconciled first.
D2 Automation Knowledge
Production REST API Integration Checklist
The controls D2 checks before treating an API workflow as production-ready: auth, pagination, limits, validation, timeout, retries, schema drift and auditability.
Written by: D2 Automation SystemsReviewed by: D2 Systems EngineeringPublished: 2026-08-21Updated: 2026-08-21
Direct answer
The practical answer
A production API integration is more than a successful 200 response. It needs credential lifecycle management, explicit request/response validation, pagination, rate-limit handling, timeouts, retry classification, idempotency where side effects exist, schema-drift detection, durable error context and observability. The integration contract must also state what happens when either system is unavailable.
Engineering model
Reliable API integration = contract + auth + validation + rate control + retry/idempotency + observability + recovery
01 / Design rule
Authentication is a lifecycle
OAuth tokens expire, API keys rotate and scopes change. Store credentials outside workflow content, define refresh/rotation behavior and alert on authentication failures instead of repeatedly retrying them.
02 / Design rule
Pagination and rate limits change correctness
Fetching only the first page can look successful while silently losing records. Define page/cursor termination rules, respect provider limits and checkpoint long-running pulls so retry does not duplicate completed work.
03 / Design rule
Validate both sides of the contract
Validate outbound payloads before sending and validate critical inbound fields before using them. Schema drift should become a visible exception, not a null value that travels through five later nodes before failing.
04 / Design rule
Design ambiguous failures
A timeout does not prove the remote system did nothing. For side-effecting calls, query by idempotency/business key or reconcile remote state before repeating the operation.
Implementation checklist
Questions to resolve before calling the workflow production-ready.
- Document auth and scopes
- Implement pagination/cursors
- Respect 429 and rate headers
- Set connect/read timeouts
- Validate request and response schemas
- Make side effects idempotent
- Persist error context and request correlation IDs
- Monitor schema/auth/rate-limit failures
FAQ
Where should API secrets live?
In the platform's credential/secret storage or a dedicated secret manager, never embedded in exported workflow JSON, source files or public case-study evidence.
Evidence standard
Architecture knowledge, implementation evidence and production outcomes are different claims.
D2 publishes these boundaries explicitly. The methodology page explains what evidence is required before a system is described as implemented, validated or production-backed.
Read D2 evidence methodologyRelated system evidence
See the engineering decisions applied in D2 case studies.
Apply the framework