Durable Object is overloaded: the four variants and what to do

# Durable Object is overloaded

A single Durable Object instance is single-threaded: it cannot do more work than one thread allows. When requests pile up faster than the instance drains them, you get overload errors:

- `Too many requests queued.` The queued request count is too high.
- `Too much data queued.` The queued request bytes are too high.
- `Requests queued for too long.` The oldest queued request has waited too long.
- `Too many requests for the same object within a 10 second window.` Extreme overload on one instance.

## What to do

Either do less work per request, or send fewer requests per instance. In practice: split the load across more object instances (shard by a finer-grained id), move heavy computation out of the DO, or batch.

## Do not retry blindly

Overload errors carry an `.overloaded` property on the exception. Check it and back off instead of retrying: retrying an overloaded object makes the overload worse. Catch, wait, and route around.

## Related: stub creation throttling

`Your account is generating too much load on Durable Objects` is a different limit: how fast you create stubs for new or existing objects. Stub lookups are cached, so retrying after a short wait is safe here, and spreading lookups across requests helps.

## Checklist

- Read which of the four variants fired: it tells you whether the problem is count, size, latency, or burst rate.
- Shard hot objects; a single object id absorbing all traffic is the usual root cause.
- Respect `.overloaded`: back off, do not hammer.