---
title: Reliability
description: Idempotency, forward compatibility, rate limits, and the machine-readable error-code vocabulary.
sidebar:
  order: 4
---

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