---
title: Idempotency — Reference
description: Which operations are safe to retry, which need application-side care.
url: https://agentnumber.really.com/docs/reference/idempotency
doc_version: "1.0.0"
last_updated: "2026-05-15"
---

> ## Documentation index
> Fetch the complete documentation index at: https://agentnumber.really.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Idempotency

> Two operations are safe to retry without dedup keys; the rest need application-side care.

## Naturally idempotent

- [`GET /availability`](/docs/reference/availability) — read-only.
- [`GET /sms/messages`](/docs/reference/messages) — read-only history.
- [`GET /number`](/docs/reference/number) — read-only.
- [`POST /waitlist`](/docs/reference/waitlist) — duplicate emails return the original `registered_at`.

## Idempotent under specific conditions

- [`POST /subscribe`](/docs/reference/subscribe) — re-paying with the same wallet renews the subscription with the same number. The `renewed` field disambiguates.
- [`POST /auth`](/docs/reference/auth) — each call rotates tokens. Don't fire-and-retry; if you get `200`, that's your only valid bearer until next time.
- [`POST /auth/nonce`](/docs/reference/auth-nonce) — each call returns a fresh nonce, so re-calling is safe but wasteful.

## Operations that need care

- [`POST /sms/send`](/docs/reference/send) — retrying on a network timeout can produce a duplicate SMS. Check [/sms/messages](/docs/reference/messages) for the carrier `message_id` before re-sending.
- [`GET /sms/receive`](/docs/reference/receive) — atomic claim. The same row will not be returned twice. Don't retry blindly; the message you missed in a network failure is gone from the unread queue (use [/sms/messages](/docs/reference/messages) for replay).
- [`POST /voice/dial`](/docs/reference/voice-dial) — retrying after a timeout can place a duplicate call. Check call status via the presence WS or wait for the `call_id` in the response.

## Idempotency keys

We don't accept a client-supplied idempotency key today. If your retry strategy actually needs one (vs the natural / atomic properties above), open a discussion in [Payment](/docs/payment) for which rail you're on — both x402 and MPP have their own settlement-side dedup we can lean on.

## Sitemap

- [Overview](/docs/)
- [Quickstart](/docs/quickstart)
- [Authentication](/docs/auth)
- [SMS](/docs/sms)
- [Voice](/docs/voice)
- [MCP](/docs/mcp)
- [Payment](/docs/payment)

See the full [sitemap.md](/sitemap.md) for the complete index of docs pages.

---

← Previous: [Rate limits](/docs/reference/rate-limits) · Next: [Webhooks](/docs/reference/webhooks) →