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:

{
  "meta": { "requestId": "..." },
  "data": { "statesetOrderId": "..." }
}

Error:

{
  "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
• Sync Server README