HTTP API work looks simple when the demo is small.

I send a request, get some JSON back, and move on with my day. Then the project grows a login flow, cloud saves, entitlement checks, matchmaking, inventory, telemetry, or a live-ops tool, and the “simple” layer turns into the place where every failure mode meets the rest of the game.

That is usually where the trouble starts. Not because HTTP is bad. Because I treated HTTP like a transport detail instead of a contract.

What I want from an API is boring in the best way: predictable requests, predictable responses, and error handling that does not punish me every time the network hiccups.

The shape of the problem

HTTP is useful because it gives me a shared language.

Methods tell me what kind of action I am making. Status codes tell me what happened. Headers carry metadata. Bodies carry the actual data.

That sounds obvious, but a lot of game code ignores half of it and then wonders why retries are scary or debugging is awful.

Game code
   ↓
API client wrapper
   ↓ adds auth, timeout, logging, correlation id
HTTP request
   ↓
API service
   ↓
status code + headers + JSON body
   ↓
DTO validation
   ↓
game state

That little wrapper in the middle matters. I want one place that knows how requests are built, how responses are decoded, and which failures should be retried. The rest of the game should not care whether I used HttpClient, UnityWebRequest, or a platform SDK under the hood.

Start with the contract, not the code

The first mistake I see is starting from the client implementation and letting the API shape fall out later.

That works for a prototype. It does not work for a game that has to survive updates.

I get better results when I decide these things first:

  • what resource the endpoint represents
  • whether the operation is a read or a write
  • which fields are required, optional, or server-owned
  • what a successful response looks like
  • what the client should do on failure

I do not need religious REST purity to do this well. I just need the method and the path to match the intent.

A read should look like a read. A create should look like a create. A destructive action should not hide behind a query string because it was convenient once.

That means I usually aim for something like this:

  • GET /players/123/profile to read data
  • POST /players/123/inventory/consume to perform a command
  • PUT /players/123/settings when I am replacing a known resource
  • PATCH /players/123/settings when I am changing a small subset
  • DELETE /players/123/cosmetics/hat-01 when I am removing a resource

I am not trying to win style points. I am trying to make the API readable six months later, when I have forgotten the implementation and only the bug report remains.

HTTP methods are a hint about retry safety

This is where HTTP starts paying rent.

The method is not just syntax. It is a promise about how the request behaves when I have to repeat it.

The important distinction is this:

  • safe methods should not change server state
  • idempotent methods should have the same effect if repeated

In practice, that means a GET is usually safe to retry, a PUT or DELETE is usually safe to retry, and a POST is the one I treat with caution unless I add deduplication on purpose.

That matters a lot in games because networks fail at annoying times.

If a shop purchase or save upload times out, I do not want to guess whether the server processed it already. I want the API to make that answer obvious.

For writes, I usually do one of two things:

  1. design the operation so repeating it is harmless, or
  2. attach an idempotency key so the server can deduplicate the request

Stripe’s idempotency model is a good example of the second approach: the client provides a key, the server remembers the first result, and retries with the same key get the same answer instead of double-applying the operation. That is exactly the sort of behavior I want for anything expensive or player-visible.

If I own the API, I make retries explicit instead of hoping the network is kind.

Status codes are part of the API

One of the worst habits in API code is returning 200 OK for everything and putting the real outcome in a JSON field called success.

That throws away useful information.

HTTP already gives me a clean status channel, so I use it.

A few codes do a lot of work for me:

  • 200 OK — the request succeeded and there is a response body
  • 201 Created — a new resource was created
  • 204 No Content — the request succeeded but there is nothing to return
  • 400 Bad Request — the client sent invalid data
  • 401 Unauthorized — the client is not authenticated
  • 403 Forbidden — the client is authenticated but not allowed
  • 404 Not Found — the resource does not exist
  • 409 Conflict — the request collided with the current state
  • 429 Too Many Requests — the client is being rate limited
  • 500 / 503 — the server failed or is temporarily unavailable

I like this because it keeps my client logic honest.

A validation bug is not the same as a network outage. A missing entitlement is not the same as a forbidden action. A conflict is not the same as a generic failure.

If I collapse all of those into one generic error, I make the client dumber and the player experience worse.

Timeouts, retries, and backoff need to be explicit

If I let the default timeout or retry behavior make decisions for me, I usually regret it later.

Games are sensitive to latency in a way regular business apps often are not. A player will not wait forever for a purchase screen, a cloud save sync, or a matchmaking button that looks frozen.

So I set the rules myself:

  • short, explicit timeouts for player-facing flows
  • retries only for requests that are safe to repeat
  • exponential backoff with jitter when I retry
  • respect Retry-After when the server asks me to slow down
  • cancellation when the player leaves the screen or the object is destroyed

That last point is easy to ignore and painful to debug.

If a menu closes, a scene changes, or a network request is no longer relevant, I want the request to stop. Otherwise I end up applying stale data to a UI that no longer exists.

That is not an HTTP problem. It is a lifecycle problem. But HTTP code tends to expose it first.

Keep auth boring and separate from gameplay logic

Authentication should be a transport concern, not a gameplay concern.

I do not want random systems reaching into a token cache or building their own auth headers. I want the API layer to own that.

The usual shape is straightforward:

  • access token goes in the Authorization header
  • refresh token stays in a secure storage path if the platform allows it
  • gameplay code asks for a service call, not for a raw token
  • expired tokens fail in one place, not ten

And no, I do not put secrets in the URL.

Query strings get logged, cached, copied, and leaked in all the ways people forget about until they are cleaning up an incident. Headers exist for this reason.

If I can make one rule here, it is this: the rest of the game should know whether the player is authenticated, but it should not need to know how the credential is represented.

Keep DTOs away from game state

This one saves me from a lot of future regret.

The shape of a response from the server is not the same thing as the shape of my gameplay objects.

I keep those apart.

The response object is a DTO: a dumb data packet that mirrors the API contract. The gameplay object is my own model, which can enforce invariants, compute derived values, and survive API changes without pulling the whole codebase apart.

That separation helps in a few ways:

  • the API can evolve without rewriting gameplay code
  • the client can validate inputs before they touch the rest of the game
  • I can keep server-only fields out of local state
  • I can mock or replay responses in tests and tools

It is tempting to deserialize JSON straight into a live game object because it is one line shorter. That line savings is fake. The cost shows up later when the server changes a field name, adds an optional property, or returns a partial response.

I would rather have one boring mapper than a future bug hunt.

A small client wrapper is usually enough

I do not need a giant networking abstraction to get most of the benefit.

I need one place that handles the repetitive stuff:

  • base URL
  • headers
  • auth
  • JSON serialization
  • status-code mapping
  • logging
  • timeouts and cancellation

That wrapper can be tiny.

Here is the kind of shape I like in C#-style code:

public readonly record struct ApiResponse<T>(
    bool Success,
    T? Value,
    int StatusCode,
    string? ErrorMessage,
    string? RequestId);

public sealed class GameApiClient
{
    private readonly HttpClient _http;
    private readonly JsonSerializerOptions _jsonOptions;

    public GameApiClient(HttpClient http)
    {
        _http = http;
        _jsonOptions = new JsonSerializerOptions
        {
            PropertyNameCaseInsensitive = true
        };
    }

    public async Task<ApiResponse<PlayerProfileDto>> GetProfileAsync(
        string playerId,
        CancellationToken token)
    {
        using var request = new HttpRequestMessage(
            HttpMethod.Get,
            $"players/{Uri.EscapeDataString(playerId)}/profile");

        request.Headers.Accept.Add(
            new MediaTypeWithQualityHeaderValue("application/json"));

        using var response = await _http.SendAsync(
            request,
            HttpCompletionOption.ResponseHeadersRead,
            token);

        var body = await response.Content.ReadAsStringAsync(token);
        var requestId = response.Headers.TryGetValues("x-request-id", out var values)
            ? string.Join(",", values)
            : null;

        if (!response.IsSuccessStatusCode)
        {
            return new ApiResponse<PlayerProfileDto>(
                false,
                null,
                (int)response.StatusCode,
                body,
                requestId);
        }

        var dto = JsonSerializer.Deserialize<PlayerProfileDto>(body, _jsonOptions);
        if (dto is null)
        {
            return new ApiResponse<PlayerProfileDto>(
                false,
                null,
                (int)response.StatusCode,
                "Invalid or empty JSON payload.",
                requestId);
        }

        return new ApiResponse<PlayerProfileDto>(true, dto, (int)response.StatusCode, null, requestId);
    }
}

That example is deliberately plain.

The point is not the syntax. The point is that the wrapper turns a messy network exchange into a consistent result type. Once I have that, the rest of the game can stop asking whether a request failed because of transport, auth, validation, or rate limiting.

In Unity runtime code I would usually wrap UnityWebRequest instead of using HttpClient directly, but the design pressure is the same. I still want one place that owns the HTTP rules.

The mistakes I keep seeing

A few mistakes come up over and over again.

1. Treating every failure as a generic error

If a request fails, I want to know why.

I do not want a one-size-fits-all false result. I want the status code, any server message, and ideally a request ID I can hand to someone with logs.

2. Retrying unsafe writes blindly

If I repeat a non-idempotent POST after a timeout, I may create duplicate purchases, duplicate inventory grants, or duplicate save entries.

That is how support tickets are born.

3. Putting business rules in transport code

The networking layer should not decide whether a player is allowed to equip an item. It should move data.

Validation belongs close to the contract, and gameplay rules belong in gameplay code.

4. Letting the server and client disagree silently

If the server changes a field name, adds a required value, or starts returning a different shape, I want that to fail loudly in staging.

Silent fallback is not resilience if it just hides a contract break.

5. Ignoring rate limits

If an API returns 429, it is telling me to slow down.

The correct response is usually to back off, not to hammer harder.

When HTTP is a good fit, and when it is not

HTTP is a great fit for a lot of game-adjacent work:

  • account services
  • cloud saves
  • inventory and cosmetics
  • live-ops configuration
  • telemetry and analytics
  • matchmaking discovery
  • build pipelines and editor tooling

It is less exciting for high-frequency real-time simulation.

If I need to move player movement, hit detection, or frame-by-frame state at low latency, HTTP is usually the wrong tool. That is where I start looking at a persistent transport with lower overhead and better timing guarantees.

So I do not use HTTP for everything. I use it where the request/response model fits the problem.

That is usually a sign I am making a sane choice.

What I would keep in my head while designing an API

If I had to compress all of this into a short checklist, it would be this:

  • use HTTP methods for their real meaning
  • return real status codes, not just success = true
  • make retries safe or explicit
  • respect Retry-After and add backoff
  • keep auth in the API layer
  • separate DTOs from gameplay state
  • log request IDs and useful failures
  • use one wrapper, not ten one-off request paths

That is enough to keep most API work from turning into a maintenance tax.

The hard part of HTTP programming is not sending the request. The hard part is making the request safe to repeat, easy to debug, and easy to evolve without breaking every caller.

If I get those three right, the rest is just plumbing.

References

These were the main references I leaned on while writing this post:

Practical takeaway

If I want game code to survive real network conditions, I stop treating HTTP like a fire-and-forget pipe.

I define the contract clearly, make retries safe, preserve status codes, and keep transport concerns out of gameplay logic. That gives me API code that is easier to debug today and much easier to change later.