Idempotent trading API clients in PHP

Give every intended action one identity

A client should assign an idempotency key before its first submission and retain that key through every retry. The key identifies the intended business action, not an individual HTTP attempt. Creating a new key after a timeout can turn one uncertain request into two accepted orders.

Persist the key with the local request state before sending. Store the payload fingerprint, creation time, account, endpoint, and latest known remote result. Refuse to reuse the key for a different payload.

• Generate the key before network I/O.
• Persist intent and payload fingerprint together.
• Keep the same key through bounded retries.
• Reject local key reuse with changed parameters.

Treat timeouts as unknown outcomes

A timeout says the client did not receive a complete response. It does not prove the server rejected the action. Query request or order state before resubmitting when the API provides a lookup mechanism. If state cannot be resolved, stop automatic retries and surface an operator-visible unknown state.

Separate transport errors, authentication failures, validation failures, rate limits, and accepted asynchronous work. Each category needs a different retry rule.

Reconcile local and remote state

A durable client keeps a small state machine: prepared, submitted, acknowledged, terminal, rejected, or unknown. Polling and event streams should update the same record using monotonic transitions. Late messages must not move a terminal request back into a pending state.

Recovery should begin by replaying unresolved local records against the remote source of truth. Logs need the local action ID, remote request ID, account, endpoint, response category, and retry count without recording credentials or signed payload secrets.

• Bound retries and apply jitter.
• Use server time or a documented clock-skew policy.
• Reconcile after process restarts.
• Alert on requests that remain unknown beyond the defined window.