Why does the API say a record does not exist right after we created it?
Because many platforms accept writes on one store and serve reads from a replica or a search index that lags behind. Your create succeeded; the read hit a copy that has not caught up. Never assume read-after-write consistency. Use the identifier the create call returned instead of searching for the record, and retry lookups with a short backoff before treating absence as failure.
Write here, read there
Large multi-tenant platforms do not serve every request from one database. Writes land on a primary store; reads are spread across replicas, caches and search indexes so the product stays fast under load. Those copies converge in a moment, but a moment is long enough for your integration to ask a question and get an answer that is already out of date.
This is a design choice, not a defect, and it is why an API can honestly return "not found" for a record it just told you it created.
Where you will run into it
- Search endpoints lag record endpoints. Fetching by id works immediately; finding the same record by phone number may take longer.
- Reporting endpoints lag transactional ones. Some report and summary endpoints recompute on a schedule and can be minutes or a full day behind the operational screens.
- Webhooks can arrive early. The event fires before related objects are queryable, so the handler that immediately fetches the invoice finds nothing.
- Aggregates settle later. Totals pulled soon after the period ends can change as late writes land.
Patterns that survive it
Use what the write returned. If the create call gives you an id, store it rather than searching for the record you just made. Where a lookup is unavoidable, retry with a short backoff and a cap, and treat a miss inside that window as "not yet" rather than an error worth alerting on.
Then let the reconciliation sweep be the safety net. Anything the immediate path could not resolve gets picked up later by the scheduled pull, which is the same mechanism that covers missed webhook deliveries. One backstop covering several failure modes is better than four special cases.
It also means your numbers move
Eventual consistency has a reporting consequence people rarely connect to it. A report pulled at 8am for the prior day may not equal the same report pulled at noon, because late-settling records arrived in between. Neither number is a bug.
The fix is a policy rather than code: define a cutoff after which a period is considered closed, restate deliberately if something changes after that, and put the data-through time on the report itself. That policy is what keeps automated briefs from contradicting themselves between the morning and the afternoon.
Topics: consistency · API behavior · sync design · reliability
Have a version of this question about your own business?
The useful answer usually depends on which systems you run and how they're connected. That's a conversation, not a blog post.