Reliability

Idempotency, forward compatibility, rate limits, and the machine-readable error-code vocabulary.

Idempotency

Every POST accepts an Idempotency-Key header. Reusing the same key on the same endpoint returns the original result instead of repeating the action. Keys are retained long enough for any reasonable retry policy.

Forward compatibility

Within v1, new fields, enum values, error codes, item types, and endpoints are non-breaking additions. Clients must tolerate values they do not yet know. Breaking changes use a new version prefix and are announced in advance.

Rate limits

Requests are rate limited per API key. A 429 response carries Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset. Default limits are confirmed during onboarding and sized to the integration.

Error codes

Errors use a stable machine-readable vocabulary: validation_error, state_conflict, environment_mismatch, unsupported_destination, invalid_api_key, not_found, and rate_limited. Each operation lists its possible HTTP error codes in x-error-codes; partial-success batch responses carry row-result codes in their result body.

Pagination

Bounded collections use a page envelope with page and page_size query parameters. The event stream uses the starting_after cursor instead.