OOmnistu

Blog / Engineering Playbooks

Engineering Playbooks

API design basics for mobile apps: methods, retries and safe failure

Review HTTP methods, retries and failure handling when designing mobile APIs that must cope with interrupted connections.

OOmnistu
Reviewed 2026-11-16 · 3 min read

At a glance

  • RFC 9110: the method defines what a request means - a safe method like GET must not do unsafe work.
  • PUT and DELETE are idempotent: a repeat leaves the same final state. POST is not.
  • A timed-out POST leaves you unable to know whether the server created the resource.
  • Idempotency-Key: one unique key per intended operation, reused on its retries.

Phones lose signal in lifts, tunnels and trains. An app that sends an order, loses connection and sends it again can charge a customer twice. A few HTTP rules address this kind of problem. This article covers one narrow area: choosing the right request method and handling retries.

What the HTTP standard says

RFC 9110 (https://www.rfc-editor.org/info/rfc9110/) defines HTTP semantics. Three points matter here.

The method defines what a request means. The RFC says request semantics live in the method, and a resource cannot treat a request in a manner inconsistent with the semantics of its method. A client can expect a resource to avoid unsafe actions when processing a safe method such as GET.

PUT and POST carry different intent. The content of a PUT represents the desired state of the target resource after the request is applied. The content of a POST represents information to be processed by the target resource.

Idempotency concerns the intended effect, not permission to retry without limits. The IETF Idempotency-Key draft (https://datatracker.ietf.org/doc/html/draft-ietf-httpapi-idempotency-key-header/) summarizes RFC 9110: methods such as OPTIONS, HEAD, GET, PUT and DELETE are idempotent: the intended effect on the server of multiple identical requests is the same as one. This does not require identical response codes or eliminate incidental logging. POST and PATCH are not idempotent by their method semantics, though an API can implement idempotency for an operation.

What this means for your API

Action Suggested method Why
Read an order GET Read-only semantics; apply appropriate retry limits
Replace a user's profile with a new version PUT Sending twice leaves the same final state
Delete a saved address DELETE Idempotent by definition
Place an order or charge a card POST Not idempotent: a repeat can create a second order

The table applies the rules above; the choices are design guidance, not part of the RFC.

The retry problem

The retry problem, and the Idempotency-Key answer

POST sent Timeout - no response Unknown: created or not? Without a keyretrying can create a second orderor a double charge With Idempotency-Keysame key on retry - result consistentwith the completed operation, no duplicate POST sent Timeout - no response Unknown: created or not? Without a keyretrying can create a second orderor a double charge With Idempotency-Keysame key on retry - result consistentwith the completed operation,no duplicate
The key must be unique per intended operation and never reused with a different payload - and the server or API must implement these semantics; the header alone does not guarantee deduplication.

The IETF draft describes the exact failure: a client sends a POST, the request times out, and the client cannot know whether the server created the resource. It cannot tell if retrying is safe.

The draft proposes an Idempotency-Key request header so POST and PATCH can be made fault-tolerant. The key must be unique and must not be reused with a different request payload. Note that this document was an Internet-Draft in the version we read, so it is a proposal, not a finished standard. Check its current status before relying on the header name. Some payment APIs implement a similar idea in their own way.

A practical pattern

  1. The app creates a unique key for each intended order operation, reusing it for retries of that same operation rather than creating a fresh key for each retry tap.
  2. It sends the key with the POST.
  3. If the request times out, the app retries with the same key.
  4. With server-side idempotency implemented for that endpoint, a retry after completion returns a result consistent with the completed operation instead of creating another order. Concurrent requests need documented conflict handling; a header by itself does not add this behavior. The server must scope key lookups to the authenticated client and enforce payload consistency and expiry policy.

Limits

RFC 9110 is long. We used its published method semantics and summaries, not the full method definitions or status code sections, so this article does not cover status codes, caching or authentication.

By Omnistu.

Sources

Previous
Android runtime permissions: how a well-behaved app asks, and what to check