> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gumnut.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Named Creates and Retries

> Safely retry album, person, and library creation when a request may have succeeded

When a create request times out after the server may have accepted it, you can
retry a named album, person, or library create with the same fields. Gumnut
checks for a matching named resource before creating another one.

## How matching works

Gumnut matches names within the resource's scope:

* Albums and people match within the selected library.
* Libraries match within your account, including libraries in the trash.
* Matching ignores surrounding whitespace and letter case.
* Only fields you include in the create request must match. Omitted fields do
  not overwrite values on an existing matching resource.

Unnamed person creates are always new. Use an update endpoint when you want to
rename an existing resource rather than create or find one by name.

## Read the create response

The status code tells you whether the request created a row or found one that
already matched:

| Status         | Meaning                                                                                                                                       |
| -------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| `201 Created`  | Gumnut created a new resource. A new album starts empty, and a new person has no faces until you assign them.                                 |
| `200 OK`       | Gumnut returned an existing resource with a matching name and matching supplied fields. An existing album or person may already contain data. |
| `409 Conflict` | A supplied field differs on the matching resource, or the requested name is reserved. The existing resource is not changed.                   |

Libraries keep their names reserved while they are in the trash, so creating a
library with the name of a trashed library returns `409` until that library is
purged. A name collision during an update also returns `409`; choose a free
name before retrying the rename.

## Retry a failed request

If the response was lost, retry the same named create with the same selected
library and supplied fields. Use the returned resource ID in the rest of your
workflow regardless of whether the response was `200` or `201`.

For albums, do not assume a `200` response represents an empty album: another
request may already have added assets to it. A `201` response starts with an
empty album, so add assets after the create succeeds.

A retry is not guaranteed to return the same ID if the resource was renamed,
deleted, or the selected library changed between requests. Treat a `409` as a
deterministic conflict instead of repeatedly sending the unchanged request.

## Related guides

* [API Overview](/guides/apis/overview)
* [Library Sharing](/guides/apis/library-sharing)
* [People and Faces](/guides/apis/faces-and-people)
* [Requests & Responses](/guides/apis/requests-and-responses)