Request Timeout

Overview

What it means and why it exists

A request timeout is the limit a client or server places on how long an API operation may wait before treating communication as incomplete. It does not establish whether the remote operation executed.

How it works

When an HTTP request exceeds its configured deadline, the caller receives a timeout error or no response. The server may still have accepted the operation, created a payment record or sent a payout. The client needs a known request reference or idempotency key to determine the outcome before deciding whether to retry.

Technical details worth understanding

Timeout budgets should reflect endpoint behavior. A read-only status query can often be retried more freely than a money-moving instruction. Exponential backoff, capped attempts and separate connection/read timeouts reduce cascading overload. Correlation IDs and observability are essential for tracing ambiguous outcomes.

What can go wrong

Automatically repeating a payout POST after every timeout can pay a beneficiary twice. Increasing the timeout forever only hides performance and reliability issues. A locally timed-out call is not proof of a blockchain failure, customer nonpayment or provider outage.

Practical checks

Classify endpoints as safe reads or potentially money-moving writes. Record request IDs so a timeout triggers status lookup rather than a fresh payout. Use finite connection and read deadlines with bounded retries. Expose ambiguous state in the operator dashboard until the remote outcome is proven.

Related concepts

Payment Status API, Webhook, API Key.

Further reading

OWASP — REST Security Cheat Sheet.