---
updatedAt: 2026-08-26T04:25:17.000Z
agentTools:
  projectIndex: https://docs.sodagift.com/llms.txt
---

# Idempotency & retries

Make order creation safe to retry with external_reference_id.

Network timeouts happen. Because orders spend real money, build your integration so a retry can never send the same gift twice.

## `external_reference_id` — your idempotency key

When creating an order, pass a unique `external_reference_id` (your own order ID, a UUID without dashes, etc. — alphanumeric, 1–100 characters):

```json
{
  "item": { "id": 5000 },
  "delivery": { ... },
  "external_reference_id": "campaign2026reward0042"
}
```

The guarantee: **within your account, only one order can ever exist per `external_reference_id`.** If you send a create request with a value that already exists, no new order is created — the API returns the **existing order** with a normal `200` response.

This makes order creation safe to retry:

1. Request times out → you don't know if the order was created.
2. Retry with the same `external_reference_id`.
3. If the first request succeeded, you get that order back. If it didn't, a new order is created. Either way: exactly one order.

Without `external_reference_id`, every create request makes a new order — there is no deduplication.

> 📘 You can also look orders up by this value later — useful for reconciliation:
>
> `GET /v1/orders?external_reference_id=myfirstorder001&page=0&element_size=10`
>
> Note that `page` and `element_size` are **required** parameters on this endpoint — omitting them returns a `400`.

## When to retry

| Situation                                       | What to do                                                                                  |
| ----------------------------------------------- | ------------------------------------------------------------------------------------------- |
| Timeout / connection error on `POST /v1/orders` | Retry with the same `external_reference_id`                                                 |
| `500` with `errorCode: order_retry_needed`      | A temporary concurrency conflict — retry a few times with short backoff                     |
| `429 rate_limit_exceeded`                       | Wait 1 second, then retry ([Rate limiting](https://docs.sodagift.com/docs/rate-limiting-1)) |
| Any other `4xx`                                 | Don't retry — fix the request ([Errors](https://docs.sodagift.com/docs/errors))             |

## Resending a delivered gift

Retrying and **resending** are different: if a recipient lost the email or mistyped nothing on your side, use [`POST /v1/orders/{order_item_id}/resend`](https://docs.sodagift.com/reference/resendorderitem-1) to re-deliver an existing order item. Resend is available for `EMAIL` and `TEXT` order items only; other methods return `resend_not_allowed`.