> ## 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.

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

<Warning>
  Keep the `requestId` from `meta` on every response, success or failure. It is
  the only handle that ties a call here to the downstream integration attempt it
  produced, and support cannot trace a failed sync without it. Log it before you
  branch on the result, not inside the error path — the calls that are hardest
  to explain later are the ones that returned `200`.
</Warning>

## Next steps

<CardGroup cols={2}>
  <Card title="Full API contract" icon="file-contract" href="/stateset-sync-server-api-contract">
    The complete HTTP and gRPC contract this summarises.
  </Card>

  <Card title="gRPC dispatch" icon="server" href="/stateset-sync-server-grpc-dispatch">
    Getting orders into the Sync Server durably.
  </Card>

  <Card title="gRPC flow" icon="diagram-project" href="/stateset-sync-server-grpc-flow">
    What happens to an order after it is accepted.
  </Card>

  <Card title="ACP guide" icon="handshake" href="/stateset-sync-server-acp-guide">
    Protocol support built on this contract.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.