Skip to main content

​
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. (Hypertext Application Language) is the link format Sumvin uses — the caller does not hardcode URLs; they follow the links in the response. 
{
  "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. The error_code field uses the format {DOMAIN}-{STATUS}-{SEQUENCE}. 
{
  "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

​
Referenced from