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

# Sync Server API Basics

> Base URLs, envelopes, error codes, and idempotency.

# Sync Server API Basics

This guide summarizes the core HTTP and gRPC contract for the Sync Server.

## Base URLs & Versioning

* HTTP base path: `/v1`
* OpenAPI: `/api-docs/openapi.json`
* Docs UI: `/docs/` or `/swagger-ui/`
* Responses include `x-api-version` and `x-api-supported-versions`

## Response Envelopes

Success:

```json theme={null}
{
  "meta": { "requestId": "..." },
  "data": { "statesetOrderId": "..." }
}
```

Error:

```json theme={null}
{
  "meta": { "requestId": "..." },
  "error": { "code": "validation_failed", "message": "..." }
}
```

## Error Codes (Common)

* `validation_failed`
* `rate_limit_exceeded`
* `integration_missing`
* `upstream_error`
* `internal_error`

## Idempotency

* Order creation is idempotent on `shopify_order_id`
* Write endpoints accept `idempotency-key` (cached for 24h)
* Retries return `idempotency-replayed: true`

## Related Documentation

* [API Contract](/stateset-sync-server/API_CONTRACT)
* [Sync Server README](/stateset-sync-server/README)