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

# HAL links, RFC 7807, idempotency, pagination

> The four cross-cutting HTTP conventions every Sumvin API follows.

# HAL links, RFC 7807, idempotency, pagination

Every Sumvin API — Platform API and SIS — applies the same four HTTP conventions. Once you know them, they apply everywhere.

## HAL `_links`

Every response includes a `_links` object with navigation and action links. <Tooltip headline="HAL" tip="Hypertext Application Language — the link format used on every Sumvin response." cta="Glossary →" href="/glossary">HAL</Tooltip> (Hypertext Application Language) is the link format Sumvin uses — the caller does not hardcode URLs; they follow the links in the response.

```json theme={null}
{
  "user": { "id": 42, "email": "alice@example.com" },
  "_links": {
    "self":   { "href": "/v0/user/me",   "method": "GET" },
    "wallets":{ "href": "/v0/wallets",   "method": "GET" },
    "kyc":    { "href": "/v0/kyc/status","method": "GET" }
  }
}
```

Action links (like `set-primary`, `delete`, `freeze`) only appear when the action is permitted for the resource's current state.

## RFC 7807 Problem Details

Every error follows [RFC 7807](https://tools.ietf.org/html/rfc7807). The `error_code` field uses the format `{DOMAIN}-{STATUS}-{SEQUENCE}`.

```json theme={null}
{
  "type": "https://api.sumvin.com/errors/wal-404-001",
  "title": "Wallet Not Found",
  "status": 404,
  "detail": "No wallet found with ID 12345",
  "instance": "/v0/wallets/12345",
  "error_code": "WAL-404-001",
  "trace_id": "abc-123-def"
}
```

Share the `trace_id` with support to debug a specific request.

## Idempotency

Several create endpoints are idempotent. Creating a resource that already exists returns **`208 Already Reported`** with the existing resource, not an error. Retries are safe.

## Async and pagination

* **Async operations** return **`202 Accepted`** with a `_links.self` poll target. Poll until the operation reaches a terminal state.
* **List endpoints** use offset-based pagination (`?offset=0&limit=50`). When more results are available, `next` and `prev` links appear in `_links`.

## See also

* [API conventions](/api-conventions) — the full reference
* [Error handling](/error-handling) — retry strategy and error taxonomy
* [Realtime events](/concepts/realtime-events) — why polling beats pushing today

## Referenced from

* [Introduction](/introduction)
* [Quickstart](/quickstart)
* [Wallets guide](/guides/wallets)